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Preface 


TSO Extensions Guide to Writing a Terminal Monitor Program or a Command 
Processor describes features of TSO/E that each installation can replace, modify, 
or add to adapt the command system to the installation’s particular needs. This 
book is intended for programmers who are responsible for modifying portions of 
TSO/E. It documents TSO Extensions for both MVS/Extended Architecture 
(MVS/XA) and MVS/370. The major differences between TSO/E running under 
MVS/XA and MVS/370 are explained in “MVS/Extended Architecture 
Considerations.” 


The book discusses the terminal monitor program and the command processors 
from the viewpoint of the TSO/E system programmer’s ability to replace or 
modify them. It describes the programming features provided within TSO/E for 
user-written terminal monitor programs, command processors, and application 
programs. These features include: 


e Service routines 
e Macro instructions 


e SVCs 


This book contains the information programmers require about the following 
topics: 


e Writing a TSO terminal monitor program 

@ Writing a TSO command processor 

e Writing a program that uses TSO to: 
— Invoke another program, TSO command, or CLIST 
— Use CLIST variables 


It also discusses: 


e The functions that a terminal monitor program or a command processor 
should provide for the TSO/E user. 


e The macro instructions that provide these functions. 
e@ The service routines that can be used to provide these functions. 
The book contains the following chapters: 


1. Introduction 
2. Terminal Monitor Program 


3. Command Processors 
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4. MVS/Extended Architecture Considerations 
5. TSO Service Routine (IKJEFTSR) J 
6. Program Access To CLIST Variables--IKJCT441 

7. Processing Terminal Requests -- The TSO Service Routines 

8. Message Handling 

9. Attention Interruption Handling -- The STAX Service Routine 


10. Dynamic Allocation of Data Sets -- The Dynamic Allocation Interface 
Routine (DAIR) 


11. Using BSAM or QSAM for Terminal I/O 

12. Using the TSO I/O Service Routines for Terminal I/O 

13. Using the TGET/TPUT/TPG SVC for Terminal I/O 

14. Using Terminal Control Macro Instructions 

15. Command Scan and Parse -- Determining the Validity of Commands 
16. Catalog Information Routine IKJEHCIR) 

17. Default Service Routine UKJEHDEF) 

18. Testing a Newly-Written TMP or CP -- The TEST Command 


The first three chapters describe the functions performed by terminal monitor Jd 
programs and command processors. The fourth chapter describes programming 
considerations for MVS/XA systems. The fifth chapter describes a TSO/E 

interface that allows an unauthorized program or command processor to invoke a 

TSO/E command, program, or CLIST, regardless of whether or not the invoked 

function is authorized. The sixth chapter describes a TSO/E interface that allows 

TSO to access CLIST variables from application programs. The seventh chapter 

describes how to interface with the TSO service routines to process terminal 

requests. The eighth chapter describes TSO messages. 


The remaining chapters describe the macro instructions, service routines, and 
facilities a programmer can use to provide the required functions. These macro 
instructions, service routines, and facilities can be used to: 

@ Issue messages 


@ Schedule and process attention interruptions 


e Allocate, free, concatenate, and deconcatenate data sets during program 
execution 


@ Provide I/O between a program and a terminal 
@e Control terminal functions and attributes 


@ Determine the validity of commands, subcommands, and operands entering ») 
the system 
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e Retrieve information from the system catalog 
e Construct a fully-qualified data set name. 


The last chapter describes the TEST command and how you can use TEST to test 
a newly written terminal monitor program (TMP) or command processor (CP). 


If you need to know which release of TSO/Extensions is installed in order to use 
the functions associated with a particular release, see the TSO/E User's Guide. 


The TSO/E User’s Guide explains how to determine the release of TSO/E that is 
installed. 


Prerequisite and Reference Publications 


This book assumes you are familiar with the structure of TSO. You need the 
following publications for reference: 


For MVS/Extended Architecture 
MVS/Extended Architecture Data Management Macro Instructions, GC26-4014 
MVS/Extended Architecture Data Management Services, GC26-4013 
MVS/Extended Architecture VSAM Programmer's Guide, GC26-4015 


MVS/Extended Architecture System Programming Library: Data Management, 
GC26-4010 


System Programming Library: TSO Extensions Planning and Installation Volume 
1, SC28-1379 


System Programming Library: TSO Extensions User Exits and Modifications 
Volume 2, SC28-1380 


System Programming Library: TSO Extensions Command and Macro Reference 
Volume 3, SC28-1381 


Data Areas 


(for MVS/System Product Version 2 JES2) LYB8-1191 
(for MVS/System Product Version 2 JES3) LYB8-1195 


Macro Usage Table 


(for MVS/System Product Version 2 JES2) LYB8-1193 
(for MVS/System Product Version 2 JES3) LYB8-1197 
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For MVS 370 


Symbol Usage Table 


(for MVS/System Product Version 2 JES2) LYB8-1192 
(for MVS/System Product Version 2 JES3) LYB8-1196 


TSO Extensions Command Language Reference, SC28-1307 

TSO Extensions Command Processor Logic, Volume I: ACCOUNT, LY28-1503 
TSO Extensions Command Processor Logic, Volume II: EDIT, LY28-1504 
TSO Extensions Command Processor Logic, Volume IIT: TEST, LY28-1137 
TSO Extensions Command Processor Logic, Volume IV, LY28-1506 


TSO Extensions Terminal Monitor Program and Service Routines Logic, 
LY28-1308 


TSO Extensions User's Guide, SC28-1333 
TSO Extensions Terminal Messages, GC28-1310 


MVS/Extended Architecture System Programming Library: 31-Bit Addressing, 
GC28-1158 


System/370 Extended Architecture Principles of Operation, SA22-7085 
Refer to MVS/System Product Version 2 General Information Manual, GC28-1118 
for the order numbers of the following MVS/XA books on the level that you are 


using: 


MVS/Extended Architecture System Programming Library: Initialization and 
Tuning 


MVS/Extended Architecture JCL 


MVS/Extended Architecture System Programming Library: System Macros 
and Facilities 


OS/VS2 MVS Data Management Macre Instructions, GC26-3793 

OS/VS2 MVS Data Management Services Guide, GC26-3783 

OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide, GC26-3838 
OS/VS2 System Programming Library: Data Management, GC26-3830 


System Programming Library: TSO Extensions Planning and Installation Volume 
1, SC28-1379 


System Programming Library: TSO Extensions User Exits and Modifications 
Volume 2, SC28-1380 
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J 


System Programming Library: TSO Extensions Command and Macro Reference 
Volume 3, SC28-1381 


TSO Extensions User's Guide, SC28-1333 
Data Areas, LYB8-1119 
Macro Usage Table, LYB8-1120 
Symbol Usage Table, LYB8-1121 
TSO Extensions Command Language Reference, SC28-1307 
OS/VS2 TSO Command Processor Logic, Volume I: ACCOUNT, SY28-0651 
OS/VS2 TSO Command Processor Logic, Volume II: EDIT, SY33-8548 
OS/VS2 TSO Command Processor Logic, Volume III: TEST, SY35-0004 
OS/VS2 TSO Command Processor Logic, Volume IV, SY28-0652 
OS/VS2 TSO Terminal Monitor Program and Service Routines Logic, GC28-0645 
TSO Extensions Terminal Messages, GC28-1310 
System 370/Principles of Operation, GA22-7000 
Refer to MVS/System Product Version 1 General Information Manual, GC28-1025 
for the order numbers of the following MVS/370 books on the level that you are 
using: 
OS/VS2 System Programming Library: Initialization and Tuning Guide 
OS/VS2 JCL 
OS/VS2 System Programming Library: Supervisor 


For MVS/Extended Architecture and MVS/370 


System Programming Library: TSO Extensions Planning and Installation Volume 
1, SC28-1379 


System Programming Library: TSO Extensions User Exits and Modifications 
Volume 2, SC28-1380 


System Programming Library: TSO Extensions Command and Macro Reference 
Volume 3, SC28-1381 


TSO Extensions User's Guide, SC28-1333 
TSO Extensions Command Language Reference, SC28-1307 
TSO Extensions Terminal Messages, GC28-1310 
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Referenced Products 


EY 
1. MVS/Extended Architecture (MVS/XA) refers to Data Facility Product J 
(5665-284) and MVS/System Product Version 2 - JES2 (5740-XC6) or 
MVS/System Product Version 2 - JES3 (5665-291). 


2. VTAM, TSO/VTAM, and ACF/VTAM refers to the program product 
ACF/VTAM Version 2 (5665-280). 


3. TCAM and TSO/TCAM refers to the program product ACF/TCAM Version 
2 Release 4 (5735-RC3). 


4. TSO/E refers to the program product TSO Extensions (5665-285). 
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Summary of Amendments 


Summary of Amendments 
for SC28-1136-4 
for TSO Extensions Release 3 


This revision applies to TSO Extensions Release 3 in an MVS/XA environment. 
It documents enhancements to the TSO service facility that enable it to invoke a 
CLIST. 


This revision also incorporates minor technical corrections and editorial changes 
throughout the book. 


Summary of Amendments 
for SC28-1136-3 
for TSO Extensions Release 2.1 


This revision describes the changes in TSO Extensions Release 2.1 to allow 
command scan and parse to accept double-byte character set data. These changes 
apply only to an MVS/XA environment when the PTF for APAR OZ91711 is 
installed on your system. 


There are minor technical corrections and editorial changes throughout the book. 
Chapter 6, “Program Access to CLIST Variables,” and Appendix B, “Using 
VTAM Full-Screen Mode,” have been rewritten. 


Summary of Amendments 

for SC28-1136-2 

as Updated December 7, 1984 
For TSO Extensions Release 2.1 


This edition supports TSO Extensions Release 2.1. The changes apply to the 
MVS/Extended Architecture environment only. TSO/E Release 2.1 supports the 
following: 


e Increased virtual storage, which has most I/O service routines and 


miscellaneous service routines executing in 31-bit addressing mode and 
accepting input above or below the 16-megabyte line. 


Summary of Amendments XX1 


e The include control character in the HELP data set, which allows the 
insertion of additional help information into existing help members. : 
) 


Minor technical corrections and editorial changes are made throughout the book. 
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Chapter 1. Introduction 


TSO/E consists of many relatively small, functionally distinct modules of code. 
One major benefit of this modular construction is that the installation can add to 
or modify TSO/E to better suit the needs of its users. You can add to or replace 
IBM-supplied code with your own, and delete those functions of TSO/E which 
you do not require. 


TSO/E is composed of modules that communicate with the user and perform the 
work requested by him. Modifications to the control program should be made 
only by system programmers responsible for the proper functioning of TSO within 
MVS. Each installation can replace or modify the terminal monitor program 
(TMP), or any of the command processors. 


If you choose to write your own terminal monitor program or a command 
processor, you can use the service routines, command processors, and macro 
instructions supplied with TSO/E or modified to support TSO/E to provide many 
of the functions required by a TMP or a command processor. 


TSO/E also provides the user with the TSO service routine (IKJEFTSR). An 
unauthorized program or command processor can invoke a command, program, 
or CLIST via IKJEFTSR, regardless of whether or not the invoked function is 
authorized. 


The Terminal Monitor Program (TMP) and Command Processors 


The terminal monitor program is a problem program that accepts and interprets 
commands. The TMP also causes the appropriate command processor to be 
scheduled and executed. 


A terminal monitor program must be able to communicate with the user at the 
terminal, load and pass control to command processors, respond to abnormal! 
terminations at its own task level or at lower levels, and respond to and process 
attention interruptions. 


When a user logs on to TSO/E, the user must either specify the name of a 
LOGON procedure by the LOGON command or accept that user’s default 
procedure name from the user attribute data set (UADS). In either case, the 
program named in the EXEC statement of the LOGON procedure is attached 
during the logon as the terminal monitor program. The program named in the 
EXEC statement can be either the TMP supplied with TSO/E, one provided by 
the installation, or one you have written yourself. 
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Once the logon has completed, the terminal monitor program requests the user at 
the terminal to enter a command name. The IBM-supplied TMP writes a 
READY message to the terminal to indicate that a command should be entered. 
The TMP determines if the response entered is a command. If the response is a 
command, the TMP attaches the requested command processor (CP), and the 
command processor performs the computing functions requested by the user at 
the terminal. 


When writing your own command processors, keep in mind that you can add 
them to the IBM-supplied command library, concatenate your own command 
library to the one supplied by IBM, or replace the entire TSO/E command library 
with your own. 


Command processors (CPs) must be able to communicate with the user at the 
terminal, respond to abnormal terminations, and process attention interruptions. 
If required, command processors must be able to load and pass control to 
subcommand processors, as well as process abnormal terminations of 
subcommand processors. 


Basic Functions of Terminal Monitor Programs and Command 
Processors 


You can see from the preceding discussion that any terminal monitor program 
and any command processor must provide four basic functions: 


1. Both the TMP and command processors must be able to communicate with 
the user at the terminal. 


2. The TMP must be able to load and pass control to a command processor. If 
a command processor has subcommand processors, it must be able to load 
and pass control to them. 


3. Both the TMP and command processors must be able to intercept and 
investigate abnormal] terminations. 


4. Both the TMP and command processors must be able to respond to and 
process attention interruptions entered from the terminal. 


You can provide each of these functions for a terminal monitor program or a 


command processor by using a service routine or a macro instruction provided 
with or modified to support TSO/E. 
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Communicating with the User 


C 


There are three ways a program running under TSO/E can communicate with a 
user: 


1. The BSAM or QSAM access methods. 


2. The STACK, GETLINE, PUTLINE, and PUTGET I/O service routines. 
These routines are invoked by the STACK, GETLINE, PUTLINE, and 
PUTGET macro instructions respectively. They provide the following 
functions: 


STACK - The STACK service routine establishes and changes the source of 
input by adding elements to, or deleting elements from, an internally 
maintained input stack. The top element on the input stack determines the 
current source of input. 


GETLINE - The GETLINE service routine obtains and returns all input lines 
other than commands, subcommands, and responses to prompting messages. 
(A prompting message asks the user at the terminal to supply required 
information.) The GETLINE service routine returns these lines of input from 
the input source designated by the top element of the input stack. 


PUTLINE - The PUTLINE service routine formats output lines, writes them 
to the terminal, and chains second level messages to be written in response to 
a question mark from the terminal. 


— PUTGET - The PUTGET service routine writes a message to the terminal 
and obtains a response from the terminal. A message written to the terminal 
that requires a response is called a conversational message. 


3. The TGET, TPUT, and TPG supervisor call. A supervisor call routine, SVC 
93, is invoked by the TGET, TPUT, and TPG macro instructions. TGET, 
TPUT, and TPG provide a route for I/O to a terminal. 


Each of these methods performs different functions and is thus suited for 
particular I/O situations. The programmer designing his own TMP or command 
processor must understand which of the I/O methods best provides the I/O 
support required in different programming situations. 


Passing Control to Command and Subcommand Processors 


A terminal monitor program must be able to recognize a command name entered 
into the system, load the requested command processor, and pass control to it. A 
command processor must be able to perform similar functions when a 
subcommand name is entered. 


Your TMP or command processor can use the command scan service routine to 
search the input line for a syntactically valid command name or subcommand 

C name. The ATTACH macro instruction can then be issued to pass control to the 
requested routines and to establish ESTAI exits. (See “Responding to Abnormal 
Terminations.”) 
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When you write a command processor or subcommand processor, you can use the 

parse macro instructions to describe to the parse service routine the operands that 

may be entered with the command name. You can then use the parse service J 
routine to determine which operands are present in the input buffer. The parse 

service routine compares the information you supplied in the parse macro 

Instructions with the contents of the input buffer. This syntactical comparison 

indicates which operands are present in the input line. The parse service routine 

returns a list to the calling routine, indicating which operands were found in the 

buffer. These operands indicate to the processing routine the functions the user is 
requesting. 


Responding to Abnormal Terminations 


A programmer coding a routine to run under TSO/E should do all that is possible 
to keep that routine from causing an abnormal termination of a TSO/E user. If 
you write your own terminal monitor program or command processors, you 
should use the ESTAE or FESTAE macro instruction and the ESTAI operand on 
the ATTACH macro instruction to provide error handling exits. 


Use the ESTAE or FESTAE macro instruction to provide the address of an error 
handling routine to be given control if any routine at the same task level as the 
error handling routine begins to terminate abnormally. 


Use the ESTAI operand on the ATTACH macro instruction to provide the 
address of an error handling routine to be given control if a routine at a lower 
task level begins to terminate abnormally. ) 


Responding to Attention Interruptions 


A terminal monitor program and any command processor that accepts 
subcommands must be able to respond to an attention interruption entered from 
the terminal. TSO/E interprets an attention interruption as a signal that the user 
wants to halt current program execution, possibly to request a new command or 
subcommand. You must provide attention exits that can obtain a line of input 
from the terminal and respond to that input. 


To build the control blocks and queues necessary for the system to recognize and 


schedule your attention handling routines, use the STAX (specify terminal 
attention exit) service routine, which is invoked by the STAX macro instruction. 


Other Functions Provided with TSO/E 


Aside from the four basic functions provided by a terminal monitor program or a 
command processor, other useful time sharing functions can be obtained using 
routines provided by IBM. 
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Three of these functions are: 
1. The dynamic allocation of data sets 


2. The immediate, on-line testing of a newly-written terminal monitor program 
or command processor 


3. Invoking programs or command processors without having to first determine 
if the command processor or program runs authorized. 


These three functions are provided through the dynamic allocation interface 
routine (DAIR), the TEST command processor, and the TSO Service Routine 
(IKJEFTSR) respectively. 


Dynamic Allocation of Data Sets 


You can invoke dynamic allocation using the dynamic allocation interface routine 
(DAIR) to: 


Obtain the current status of a data set 

Allocate a data set 

Free a data set 

Concatenate data sets 

Remove data sets from a concatenation 

Build a list of attributes (DCB parameters) to be assigned to data sets 
Delete a list of attributes 


It is recommended, however, that you invoke dynamic allocation directly 
whenever possible (especially when writing new command processors) to take 
advantage of the additional functions available and to decrease system overhead. 
For a detailed description of these functions and how to invoke dynamic 
allocation directly, refer to System Programming Library: System Macros and 
Facilities. 


The DAIR interface, designed to invoke dynamic allocation for you, is 
maintained so that existing command processors do not have to be modified to 
invoke dynamic allocation directly. DAIR acts as a translator; it converts the 
DAIR parameter list it receives as input to a dynamic allocation parameter list, 
which it then passes to dynamic allocation. 


Testing a TMP or a CP 


After you have coded a new TMP or CP, you will want to test it. Before you 
enter the program into TSO/E, you can use the TEST command to simulate the 
different execution paths you expect the program to follow successfully once you 
have entered it into TSO/E. 


The TEST command permits a terminal user to test an assembly language 
program. You test a program by issuing the TEST command and the various 
TEST subcommands that perform the following basic functions: 

e Execute the program being tested from its starting address or from any 


address within the program 
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@ Display selected areas of the program as it appears in virtual storage, or 
display the contents of any of the registers ) 


@ Interrupt the program being tested at a specified location or locations 


@ Change the contents of specified program locations in virtual storage or the 
contents of specific registers 


In addition to these basic debugging functions, you can use the TEST command 
to display various control blocks, program status words, or a virtual storage map 
of the program being tested. 


TSO Service Routine 


Program Interface to TSO/E Command Processors or Other Programs 


This interface enables unauthorized command processors and programs running 
under TSO/E to execute any command, program, or CLIST, regardless of whether 
or not the command, program, or CLIST runs authorized. 


For example, an applications program written in PLI, COBOL, assembler, or any 
of the other IBM supported programming languages can use the interface, 
IKJEFTSR (alias name, TSOLNK), to invoke the ALLOCATE command 
processor to accomplish dynamic allocation of data sets. 


The TSO service routine can be invoked in both foreground and background ) 


TSO/E sessions. For additional information concerning this service see the TSO 
Service Routine chapter. ° 
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Chapter 2. The Terminal Monitor Program 


Note: Any TSO command that issues SVC 100 (SUBMIT, STATUS, CANCEL, 
OUTPUT, OPERATOR, and the ALTFILE option of ALLOCATE) does not 
function on a user-written TMP. 


The terminal monitor program (TMP) is a program that provides an interface 
between the terminal user, command processors, and the TSO control program. 
TSO LOGON causes the system initiator to attach the program named on the 
EXEC statement of the user’s LOGON cataloged procedure. This may be the 
IBM-supplied TMP or any user-supplied alternate. 


The user’s LOGON procedure, which is specified on the LOGON command, 
defines the maximum number of concurrently allocated data sets allowed in a 
given TSO session. The LOGON procedure can contain: 


e DD statements that define data sets to be used during the TSO session 


e DD statements with the DYNAM parameter that increase by one the control 
limit for dynamically allocated resources held for reuse. The DYNAM 
parameter is supported to provide compatibility with older systems. Use of 
the DYNAMNBR keyword is recommended instead. 


e DYNAMNBR keyword on the EXEC statement. 


These statements set the control limit for the number of data sets that can be 
allocated to the user at any one time during the session. The formula for 
determining the control limit is: 


Control limit = # DD statements (with and without DYNAM) + the number supplied on the 
DYNAMNBR parameter of the EXEC statement. 


If a new dynamic allocation request exceeds the control limit, the allocation 
routines automatically attempt to deallocate enough data sets, marked 
“not-in-use”, to meet the control limit. They deallocate the data sets that have 
been marked “not-in-use” for the longest time. If the request still exceeds the 
control limit, allocation fails and the user must explicitly deallocate an existing 
data set. 


Figure 2-1 shows an example of the EXEC statement in a user LOGON 
procedure. This procedure is equivalent to a LOGON procedure containing 10 
DD DYNAM statements and no DYNAMNBR operand. For a complete 
discussion of a LOGON procedure, see SPL: TSO/E User Exits and 
Modifications Volume 2. 
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Figure 2-1. 


A LOGON Procedure 


The terminal monitor program you use can be the TMP supplied with TSO, one 
provided by the installation, or one you have supplied yourself. If you choose to 
write your own terminal monitor program, use the TSO service routines and 
macro instructions described in this book to help you code the TMP and fit it 
into TSO. 


The TMP must be able to respond to the following four conditions: 


1. Normal completion of a command processor or user program, and the 
requesting of another command 


2. An error causing termination of the TMP, a command processor, or a user 
program 


3. An attention interruption from the terminal, halting execution of the current 
program. 


4. A STOP operator command, forcing a LOGOFF for the user 


. 
This section explains how to respond to these conditions. It describes in general J 
terms how the IBM-supplied TMP functions, and how it fits together with the rest 

of TSO. For a more specific description of the IBM-supplied TMP, see Terminal 

Monitor Program and Service Routines Logic. 


Terminal Monitor Program Initialization 


In a LOGON procedure, the terminal monitor program (TMP) name must appear 
as the first operand of the PGM= keyword operand on the EXEC statement. 


When the TMP is attached: 

e Register 1 contains the address of the field containing the length and data of 
the EXEC parameter. The IBM-supplied TMP uses this PARM value as the 
first command requested. The first two bytes of the PARM value are on a 
halfword boundary and contain the length of the PARM value. (The length 
value does not include the two length bytes.) 

e Register 13 contains the address of the register save area. 


e Register 14 contains the return address of the LOGON/LOGOFF scheduler. 


e Register 15 contains the entry point address of the TMP. ) 
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The TMP sets up the tables and control blocks it requires, loads the TIME 
command processor, sets up the ESTAE and ESTAI exits to respond to abnormal 

C terminations, sets up the attention exits, builds the command buffer, and 
initializes the input stack to point to the terminal. The TMP then uses the 
EXTRACT macro instruction to obtain the addresses of the STOP/MODIFY 
ECB and the protected step control block (PSCB) built by the LOGON/LOGOFF 
scheduler. 


The TMP determines whether it is running in a TSO or a batch environment by 
testing the time-sharing bit in the TCB. If the TMP is running in a batch 
environment, it will use the DATASET keyword while invoking the STACK 
service routine to cause GETLINE and PUTLINE to be directed to data sets. 
The TMP must also build the same control blocks that LOGON would have 
built. 


The IBM-supplied terminal monitor program attaches the command processor 
named in the EXEC statement PARM field. If no command was named as a 
PARM operand, the TMP issues a PUTGET macro instruction to obtain the first 
command. The TMP shares subpool 78 with the attached command processor 
but does not share subpool 0. The command processor, in turn, must share 
subpool 78 with any lower level tasks. 


The TMP should not pass in-line parameter lists to commands or TSO service 
routines. Subpool 251 should not be used for parameter lists. The command 
processor parameter list (CPPL), described later in this book, should be in 
subpool 1. You may use the IKJTMPWA macro to map the TMP work area. 


~ Requesting a Command 


Figure 2-2 summarizes the steps taken by a terminal monitor program to obtain a 
command, to pass control to the command processor, and to detach the command 
processor when it has finished. 
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Figure 2-2. Requesting a Command 


Use the PUTGET service routine to request a command from the terminal. The 
PUTGET service routine first writes a line to the terminal to inform the user that 
another command is expected, then returns a line entered in response to the 
request, and places that line into a command buffer. 


Use the command scan service routine to determine whether the line of input is a 
syntactically valid command name. 
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Use the ATTACH macro instruction (specifying an ESTAI exit routine) to pass 
control to the requested command processor. 


Your TMP must create any parameter lists expected by the command processor 
and pass them to the newly attached command processor. The IBM-supplied 
TMP passes the address of a command processor parameter list in register one. 
See the sections entitled “MVS/Extended Architecture Considerations” and 
“Processing Terminal Requests -- The TSO Service Routines” for more 
information about the interface between the TMP and command processors. 


When the command processor completes, the TMP releases it via a DETACH 
macro instruction, uses dynamic allocation to indicate that dynamically allocated 
data sets may be freed, and uses the PUTGET service routine to obtain another 
command. 

The TSEVENT macro facilitates the use of the generalized trace facility (GTF) to 
trace the attaching of a command processor by an installation-supplied terminal 
monitor program. The TSEVENT macro results in control being passed to a 
GTF hook located in the system resources manager (SRM) interface program. 


User written TMPs should issue the TSEVENT macro before attaching each 
command processor. 


Issue the TSEVENT macro instruction as follows: 


1. Load register 1 with the first four characters of the command name being. 
attached or released. 


2. Load register 15 with the last four characters of the command name. 


3. Code the TSEVENT macro instruction as shown in Figure 2-3. 


[label] | TSEVENT PPMODE 


Figure 2-3. The TSEVENT Macro Instruction Specifying PPMODE 


Intercepting an ABEND 


The terminal monitor program must be able to recognize and respond to two 
basic types of ABEND situations: 


1. An attached subtask (for example, a command processor) is terminating 
abnormally. 


2. The TMP itself or a program linked to by the TMP (for example, command 
scan) is terminating abnormally. 
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Intercepting a Subtask ABEND 


When a subtask of the terminal monitor program begins to terminate abnormally, 
the TMP ESTAI exit, specified by the TMP when it attached the subtask, receives 
control. The TMP ESTAI exit receives control under the TCB of the abending 
subtask. The subtask will already have performed its own ESTAE processing, if 
any was specified. Figure 2-4 shows the relationship between the ABEND, the 
ESTAE, and the ESTAI. For additional information about expanded recovery 
facilities available through ESTAI, refer to Supervisor Services and Macro 
Instructions. 


Terminal Monitor Program 


ESTAE Exit - For ABEND at 
TMP TCB Level. 


ESTAI Exit - For ABEND at 
daughter TCB level. 


ATTACH 


(with ESTAI operand) 
Command 


Processor 


ESTAE Exit - For ABEND at 
this TCB level 


Figure 2-4. ABEND, ESTAI, ESTAE Relationship 
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The TMP must inform the user at the terminal of the ABEND situation, and 
allow the user to enter another command. Use the PUTGET service routine, 
specifying the TERM operand, to inform the user of the ABEND and to return a 
line of input from the terminal. 


The terminal user has four options: 


1. Allow the ABEND to continue by entering a null line (pressing the ENTER 
key). 


2. Terminate processing of the ABEND by entering a command name other 
than TEST or TIME. 


3. Request any second-level messages concerning the terminating program by 
entering a question mark. 


4. Place the terminating program under the control of the TEST command 
processor by entering the command name TEST. (See “Testing a 
Newly-Written TMP or CP -- The TEST Command” later in this book.) 


Use the command scan service routine to determine what the user has entered at 
the terminal. 


If the user enters a null line, the TMP returns control to the ABEND routine, and 
the task is allowed to terminate abnormally. If the user enters a command name, 
other than TEST or TIME, the TMP processes the new command name after 
detaching the subtask. 


If the user enters a question mark, the PUTGET service routine causes the 
second-level informational message chain (if one exists) to be written to the 
terminal, again puts out the mode message, and returns the response from the 
terminal. 


When the TIME command is entered, the TMP links to the TIME command 
processor to obtain the time information. Upon completion of the TIME 
command, the user still has the above four options. 


If the user enters the TEST command, the TMP passes control to the TEST 
command processor via a SYNCH macro instruction. If any operands were 
entered on the TEST command, the TMP detaches all subtasks before invoking to 
the TEST command processor. If no operands were entered, the TMP does not 
detach any currently active subtasks. In this latter case, the user is requesting that 
the abnormally terminating task be run under the control of TEST. 


Intercepting a TMP Task ABEND 


When the TMP (or any program linked to by the TMP) causes an ABEND, the 
TMP ESTAE exit gains control. The TMP specifies its own ESTAE exit routine 
by issuing the ESTAE macro instruction. (See SPL: System Macros and 
Facilities for a discussion of the ESTAE macro instruction.) For a discussion of 
interface considerations for establishing ESTAE and ESTAI exit routines, refer to 
“ESTAE/ESTAI Exit Routines -- Intercepting an ABEND” in the section on 
command processors in this manual. 
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Your TMP ESTAE exit routine can use the contents of the system diagnostic 
work area created by the ESTAE macro instruction to determine: 


The type of error 

The cause of the error 

The PSW at the time of the ABEND 

The last PSW before the program ABEND 
The contents of the program registers 


If your TMP ESTAE exit routine cannot correct the problem, it should use the 
PUTLINE macro instruction to inform the user at the terminal that a task 
running under the TMP’s TCB is terminating abnormally. Then the TMP 
ESTAE routine should do the following: 


e IfaSYSABEND, SYSUDUMP, or SYSMDUMP data set was allocated 
during the user’s session, take a dump of the user’s region. 


e Clear the user’s region. 
e Load a fresh copy of the TMP. 


e Begin processing as if the TMP had been invoked by the LOGON/LOGOFF 
scheduler. 


To obtain additional diagnostic information, your TMP ESTAE exit routine can 
issue the SDUMP macro to obtain an SVC dump. See SPL: Supervisor or SPL: 
System Macros and Facilities for information about how to use that macro. 


If the error persists and the TMP fails again, the ESTAE routine should pass 
control to the PUTLINE service routine to notify the user. A logoff should be 
forced by returning to the LOGON/LOGOFF scheduler. 


For additional information about expanded recovery facilities available through 
ESTAE and ESTAI, refer to Supervisor Services and Macro Instructions. 


Processing an Attention Interruption 


After having been attached, the TMP must set up its attention handling facilities. 
For this initialization process, you can use the STAX macro instruction to pass 
the address of your attention handling routine to the system. 


For a discussion of interface considerations for attention exit routines, refer to 
“Specifying a Terminal Attention Exit -- The STAX Macro Instruction” later in 
this book. 


Several attention handling routines may be enqueued at any one time; that is, 
both the TMP and the currently active command processor may have issued 
STAX macro instructions. For a description of how the user can request different 
levels of attention exits, see “Attention Interruption Handling -- The STAX 
Service Routine” later in this book. 
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The attention handling routine you specify for the terminal monitor program is 
given control under any of the following conditions: 


1. An attention interruption is entered from the terminal while the terminal 
monitor program is in control. 


2. An attention interruption is received from the terminal while a program 
(other than the terminal monitor program), that has not provided an 
attention handling routine, is in control. 


3. A program other than the terminal monitor program is in control. The 
program has provided an attention exit, but the user at the terminal has 
issued sufficient attention interruptions to reach the terminal monitor 
program’s attention handling routine. As an example, if a command 
processor that has provided an attention handling routine is in control, and a 
user enters two successive attention interruptions from the terminal, the 
terminal monitor program’s attention exit receives control. 


You can defer attention interruption processing with the DEFER operand of the 
STAX macro instruction. If you do use the DEFER option, attention 
interruptions are queued as they are received, and are not processed until you 
request that the DEFER option be removed. 


Parameters Received by Attention Handling Routines 


When your attention exit routine is entered, the registers contain the following 
information: 


Register Contents 
0,2-12 Irrelevant 


| The address of the attention exit parameter list. 

13 Save area address. 

14 Return address. 

15 Entry point address of the attention handling routine. 


The attention exit parameter list pointed to by register one, contains the address 
of a terminal attention interruption element (TAIE). 


The parameter structure received by your attention exit routine is shown in 
Figure 2-5. 
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Entry from the STAX service routine 


Attention Exit Routine 


Register 1 


Attention Exit 
Parameter List 


Terminal Attention 
Interrupt Element 


Figure 2-5. Parameters Passed to the Attention Exit Routine 
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The Attention Exit Parameter List 


Figure 2-6 shows the format of the attention exit parameter list pointed to by 
register one when an attention exit routine receives control. 


Number 
of Bytes Contents or Meaning 


He The address of the terminal attention interrupt element (TAIE). 


Figure 2-6. The Attention Exit Parameter List 


The address of the input buffer you specified as the IBUF operand of 
the STAX macro instruction. Zero if you did not include the IBUF 
operand in the STAX macro instruction. 


The address of the user parameter information you specified as the 
USADDR operand of the STAX macro instruction. Zero if you did not 
include the USADDR operand in the STAX macro instruction. 


The Terminal Attention Interrupt Element (TAIE) 


The first word of the attention exit parameter list contains the address of an 
eighteen-word terminal attention interrupt element (TAIE). Figure 2-7 shows the 
format of the TAIE, which is mapped by the IKJTAIE macro. 


Number 
of Bytes Contents or Meaning 


TAIEMSGL | The length in bytes of the message placed into the input buffer you 
specified as the IBUF operand on the STAX macro instruction. Zero if 
you did not code the IBUF operand in the STAX macro instruction. 


TAIETGET | The return code from the TGET macro instruction issued to get the 


input line from the terminal. 


TAIEIAD The interruption address. The right half of the interrupted PSW. The 
address at which the program (or a previous attention exit) was 
interrupted. 


TAIERSAV | The contents of general registers, in the order 0 - 15, of the interrupted 
program. 


Figure 2-7. The Terminal Attention Interrupt Element 


If you did not include the IBUF and the OBUF operands in the STAX macro 
instruction that set up the attention handling exit, use the PUTGET macro 
instruction, specifying the TERM operand, to send a mode message to the 
terminal identifying the program that was interrupted, and to obtain a line of 
input from the terminal. 


If you specify the OBUF operand on the STAX macro instruction without an 
IBUF operand, or with an IBUF length of 0, you can then use the PUTGET 
macro instruction, specifying the ATTN operand. This causes the PUTGET 
service routine to inhibit the writing of the mode message, since a message was 
already written to the terminal from the output buffer specified in the STAX 
macro instruction. The PUTGET service routine merely returns a logical line of 
input from the terminal. 


In either of the above cases, if the user enters a question mark, the PUTGET 
service routine automatically causes the second-level informational message chain 
(if one exists) to be written to the terminal, puts out the mode message again, and 
returns a line from the terminal. 
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If you used the IBUF operand on the STAX macro instruction, note that no 

logical line processing or question mark processing is performed. If the user J 
returns a question mark, you will have to use the PUTLINE macro instruction to 

write the second-level informational message chain to the terminal. Then issue a 

PUTGET macro instruction, specifying the TERM operand, to write a mode 

message to the terminal and to return a line of input from the terminal. 


Use the command scan service routine to determine that the line of input is 
syntactically correct in the input buffer returned by the PUTGET service routine, 
or in the attention input buffer (pointed to by the second word of the attention 
exit parameter list). 


Special functions such as the TIME function should be performed immediately by 
the attention handling routine, and a new READY message should then be put 
out to the terminal, so that the terminal user may enter another command. Any 
other command should be passed to the TMP mainline routine for processing as if 
it were a newly entered command. 


Note that, with the exception of the TPUT ASID buffers for TCAM, the TGET, 
TPUT, and TPG buffers are flushed when an attention interruption is entered. If 
the user enters an attention interruption from the terminal and then enters a null 
line to continue processing, the contents, if any, of the TGET, TPUT, and TPG 
buffers are lost. 


Processing a STOP Command 
A STOP/MODIFY ECB is created by the time sharing system and can be 

obtained by your TMP by use of the EXTRACT macro instruction. During 

TMP processing, if a STOP command is indicated by a post to the STOP ECB, 

return to the LOGON/LOGOFF scheduler so that the user may be logged off the 

system. 
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Chapter 3. Command Processors 


A command processor is a program invoked by the TMP when a user at a 
terminal enters a command name. It may be link-edited into any library in the 
system link library list (LNKLSTxx) or SYS1.LPALIB. The command processor 
may be placed in a data set that is specified on the STEPLIB DD statement in a 
LOGON procedure. Execution should normally not be handled from a STEPLIB 
because of a decrease in performance during a system and TSO session. Refer to 
“Adding Commands to TSO” for a description of when a STEPLIB should be 
used. 


The internal logic of the IBM-supplied command processors is described in 
Command Processor Logic, Volumes I-IV. The command language used to 
request each of these command processors is described in the TSO/E Command 
Language Reference. 


If you choose to write your own command processors, you should be familiar 
with the service routines described in this book. 


This section discusses the relationships between the command processors and the 
rest of TSO, and provides guidelines for coding your own command processors. 


This section is divided into the following topics: 


e Adding Commands to TSO - Describes how to add a new command 
processor to TSO 


e Command Processor Coding Conventions - Describes normal interface 
conventions 


e Command Processor Use of the TSO Service Routines - Briefly discusses each 
of the TSO service routines and the situations in which they should be used 


e The ESTAE and ESTAI Exit Routines - Discusses the functions your error 
routines should provide 


e Attention Exit Routines - Discusses the need for attention handling exits and 
the functions those exits should perform 


e The HELP Data Set - Discusses the HELP data set, and the means of 
entering information into a HELP data set 
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Adding Commands to TSO 


| 
There are three methods you can use to add a new command processor to TSO. oF 


1. You can enter your command processor as a member of the partitioned data 
set SYS1.CMDLIB, via the linkage editor. 


2. You can create your own command library and concatenate it to the 
SYS1.CMDLIB data set. In this case, create new statements in the link list 
(LNKLST00 or LNKLSTxx) in SYS1.PARMLIB. 


3. Generally, unauthorized users can request that a LOGON procedure be 
created that specifies, on the STEPLIB DD statement, the name of the 
partitioned data set containing the command. 


Command Processor Coding Conventions 


The TMP uses standard linkage conventions in passing control to a command 
processor. The command processor parameter list (CPPL) is the input parameter 
list to all command processors. For more information on the CPPL, see the 
section called “Interfacing with the TSO Service Routines” later in this book. 


Command processors should contain logic that issues error messages. These 

messages should handle all error codes, expected or unexpected, from any routine 

or SVC they invoke. Whenever possible, generalized routines such as DAIRFAIL ’ 
should be used. Use of these routines allows the issuance of meaningful error J 
messages for return codes. 


When returning control to the TMP, the command processor should use standard 
linkage and set a return code in general register 15. Command procedures 
(CLISTs) may then check this code for the following conventions: 


0- normal execution 


12- termination error during execution (no error exists if a command processor is able to obtain 
required information by prompting) 


Command Processor Use of the TSO Service Routines 


Use the IBM-provided service routines described in this manual when coding your 
own command processors. Read the sections on the various service routines, 
macro instructions, and “Interfacing with the TSO Service Routines” for an 
understanding of the services they perform and how to use them. The following 
topics provide information on when to use each of the service routines. 


Note: “MVS/Extended Architecture Considerations” lists the linkage attributes 


for the TSO service routines. Additional descriptions of considerations caused by 
31-bit addressing are provided in the sections describing the routines and macros. 
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STACK Service Routine 


Use the STACK service routine to change the source of input by adding an 
element to the input stack or to reset the input stack to the terminal element 
originally specified by the terminal monitor program. 


A command processor should issue the STACK macro instruction in the 
following circumstances: 


1. Your command processor has created a series of commands to be executed 
after the command processor terminates. The command processor should 
build an in-storage list containing the commands to be executed and issue the 
STACK macro instruction to place a pointer to the list on the input stack. 


2. You may want to pass data from one of your command processors to another 
command processor. This data may be passed in storage via the input stack. 
Issue the STACK macro instruction to place a pointer to the in-storage data 
on the input stack. 


3. Your command processor performs functions similar to those performed by 
the IBM-supplied EXEC command (that is, it executes a command 
procedure). Your command processor should issue the STACK macro 
instruction to place a pointer on the input stack to the command procedure to 
be executed. 


4, Whenever one of your command processors terminates with an error 
condition, its error handling routine should issue the STACK macro , 
instruction to clear the input stack, before returning control to the TMP. The 
input stack must be cleared or command procedure (CLIST) processing will 
not be handled correctly. Commands such as DELETE and FREE do not 
flush the stack if the module requested was not found. 


Catalog Information Routine 


The catalog information routine (IKJEHCIR) retrieves information from the 
system catalog. This information may include a data set name, index name, 
control volume address, or volume ID. The information may be requested from a 
specific user catalog. If you do not specify a specific catalog, IKJEHCIR searches 
the system default catalog. An entry code indicates what kind of information is 
being requested. 


Use the CALL, CALLTSSR, or LINK macro instruction to invoke the catalog 
information routine. 


Note: For additional information concerning the catalog information routine, see 
“Catalog Information Routine (IKJEHCIR)” later in this book. 
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Default Service Routine 


The default service routine (IKJEHDEF) constructs a fully-qualified data set Jd 
name when the calling routine provides a partially-qualified data set name. A 

fully-qualified data set name has three fields: a user ID, a data set name, and a 

descriptive qualifier. 


Use the CALL, CALLTSSR or LINK macro instruction to invoke the default 
service routine. At entry, general register 1 must point to the default parameter 
list (DFPL). IKJEHDEF then invokes the catalog information routine 
(IKJEHCIR) to search the system catalog for the required qualifiers. When the 
search argument is satisfied, the default service routine returns to the calling 
control program. All of the general registers are restored except for register 15 
which contains the return code. 


Note: For additional information concerning the default service routine, see 
Terminal Monitor Program and Service Routines Logic. 


GETLINE Service Routine 


Your command processors should use the GETLINE service routine to obtain 
data. The buffer returned by GETLINE is in subpool 1, and is owned by your 
command processor. For efficient execution, issue FREEMAIN macro 
instructions within each command processor, or within each subtask created by 
the command processor, to free the GETLINE buffers it obtains. 


? 
PUTLINE Service Routine J 


Your command processors should use the PUTLINE service routine to write 
informational messages or data to the terminal and to chain second level 
informational messages. PUTLINE writes the output lines to the terminal 
regardless of the source of input. TPUT should not be used under these 
circumstances. The GNRLFAIL service routine should be used to issue 
meaningful error messages for return codes from PUTLINE. 


PUTGET Service Routine 


Your command processors should use the PUTGET service routine for prompting 
and for subcommand requests. Use the operands on the PUTGET macro 
instruction to specify logical line processing with editing and the WAIT option. 


If the user enters a question mark in response to a message issued with a 
PUTGET macro instruction, the PUTGET service routine displays the second 
level messages chained by previous PUTLINE macro instructions. If the user 
responds with a subcommand name, the second level messages are deleted and the 
storage they occupied is freed. See “PUTGET Processing” for exceptions to this 
usual method of processing. 


As with the GETLINE service routine, the buffers returned by the PUTGET 
service routine belong to, and should be freed by, the command processor. } 
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IKJEFFO2 Message Issuer Service Routine 


DAIR Service Routine 


If you make numerous insertions into messages, you should use this service 
routine instead of PUTLINE and PUTGET. Also, when you use IKJEFFO2, all 
of your messages can be placed in a single CSECT or a single module. 


You may use the DAIR service routine to obtain information about a data set 
and, if necessary, to invoke dynamic allocation routines to perform the requested 
function. However, additional functions are available if you invoke dynamic 
allocation directly. Another drawback to using DAIR is that it increases system 
overhead. For a discussion of how to invoke dynamic allocation directly, refer to 
SPL: System Macros and Facilities. 


If you are going to use DAIR, you should read the section called “Dynamic 
Allocation of Data Sets - The Dynamic Allocation Interface Routine (DAIR)” 
later in this book and adhere to the following guidelines: 


e Command processors should allocate data sets by DSNAME and use the 
DDNAMES returned by DAIR to open the data sets. If necessary, command 
processors should pass the DD names on to any subcommands or problem 
programs running under them. 


e Command processors should allow DAIR, the default service routine, or the 
parse service routine to prefix an identifier on the data set name so the 
PROFILE command’s PREFIX and NOPREFIX options are automatically 
supported. You can use the default service routine to add any data set suffix 
that exists for the data set. (The default service routine is documented in 
Terminal Monitor Program and Service Routines Logic.) 


@ Whenever the user specifies a password for a data set, the command processor 
should send the password to DAIR when allocation is requested. 


e Command processors should normally invoke DAIR to free all data sets at 
termination so other TSO users or submitted jobs can have full use of the 
data sets. 


e Before detaching terminated subcommands, command processors that accept 
subcommands should use DAIR to free any data sets allocated by the 


subcommands. 


e Command processors should use the DAIRFAIL service routine to issue 
meaningful error messages for non-zero return codes from DAIR. 
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Command Scan Service Routine 


Parse Service Routine 


Your command processors should use the command scan service routine to scan 
for valid subcommand names. The option of checking the remainder of the input 
line for non-separator characters should be requested. If no additional significant 
characters are found in the line, the command processor subroutine need not 
invoke the parse service routine to scan the command operands because none are 
present. 


Your command processors and subcommand processors should use the parse 
service routine to scan the operands entered with the command or subcommand 
name. The parse service routine returns a parameter descriptor list to the calling 
routine. The parameter descriptor list describes the operands found in the 
command buffer. 


In the parse macro instructions that define command syntax, command processors 
and subcommand processors can indicate to the parse service routine that validity 
checking exits be taken on certain types of operands. Because the parse service 
routine checks the operands only for syntax errors, you should indicate in the 
parse macros that validity checking routines be entered whenever a logical, rather 
than a syntactical, error might occur. 


The GNRLFAIL service routine should be used to issue meaningful error 
messages for non-zero return codes from the parse service routine. 


When the parse service routine prompts the user to enter a required operand, or 
to reenter a syntactically incorrect operand, the user may type in question marks 
to receive the second level messages associated with the operand. 


Prompt Mode HELP Function 


Once the second level messages are exhausted during a prompting sequence, if the 
user enters another question mark, parse processing determines whether it can 
generate a valid HELP command to provide the user with additional information. 


If the ECTNOQPR bit in the environment control table (ECT) is zero, then the 
prompt mode HELP function is active and parse processing generates a HELP 
command on the user’s behalf. Parse processing ensures that only one HELP 
command is issued during a prompting sequence for a given operand. If the user 
enters another question mark after viewing the online usage information, the NO 
INFORMATION AVAILABLE message is issued. 


The TMP sets the ECTNOQPR bit to zero before attaching a primary command, 
except the TEST and LOGON commands for which the function is not available. 
Parse sets ECTNOQPR to one before it returns control to the command 
processor. Consequently, the prompt mode HELP function is not active during 
subsequent invocations of parse within the domain of the command, nor for any 
subcommands attached by the command processor. If your command processor 
does not want the prompt mode HELP function to be active for the entire 
domain of the command, it should set the ECTNOQPR bit to one prior to 
invoking parse for the first time. 
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If your command processor accepts subcommands and wants the prompt mode 
HELP function to be available for a subcommand, it should set ECTNOQPR to 
one before attaching the subcommand. In this case, the command processor 
should ensure that the ECTPCMD and ECTSCMD fields in the ECT contain the 
primary command name and the secondary command name respectively. 


The prompt mode HELP function is active for all keyword operands of all 
commands (except the TEST and LOGON commands), including user-written 
commands. It is also active for the positional parameters of the following 
commands: ATTRIB, CALL, CANCEL, EDIT, EXEC, HELP, OUTPUT, 
RUN, and SEND. If you want to make this function available for the positional 
operands of other commands, as well as for the positional operands of 
user-written subcommands for which the prompt mode HELP function is enabled, 
you or your system programmer must update their corresponding HELP members 
as described in “Writing HELP Members” and “Updating Existing HELP 
Members” later in this section. 


Note: The prompt mode HELP function is not supported during LOGON 
processing. LOGON pre-prompt exit routines should not make the function 
active. 


ESTAE/ESTATI Exit Routine -- Intercepting an ABEND 


Linkage Considerations 


Use the ESTAE and ESTAI exits in your command processors, if they are needed, 
to keep the system operable if abnormal termination occurs. ESTAE/ESTAI exits 
should be used in such a way that the command processor gets control if a 
subcommand abnormally terminates. If you issue an ESTAE, issue it as early as 
possible in your command processor. Any ESTAE should be issued before any 
STAX. ESTAE provides the command processor with the ability to intercept an 
ABEND so that cleanup, bypass, and if possible, execution retry can be 
accomplished. (See SPL: System Macros and Facilities for a discussion of the 
ESTAE macro instruction. See Supervisor Services and Macro Instructions for a 
discussion of the ESTAI operand of the ATTACH macro instruction and for 
information about ESTAE and ESTAI exit routines.) 


Programs may issue the ESTAE and FESTAE macros, as well as the ATTACH 
macro with the ESTAI operand, in either 24- or 31-bit addressing mode. The 
ESTAE, FESTAE, and ESTAI exit and recovery routines receive control in the 
same addressing mode in which the ESTAE, FESTAE, and ATTACH macros are 
issued. When the macros are issued in 31-bit addressing mode, ESTAE, 
FESTAE, and ESTAI routines may reside above 16 Mb in virtual storage. 


The ESTAE, FESTAE, and ATTACH macros are downward incompatible. The 
MVS/Extended Architecture versions of these macros do not execute properly in 
MVS/370. For an explanation of how to select the desired macro level, see SPL: 
System Macros and Facilities. 


While not recommended, the STAE macro and the STAI operand of ATTACH 


may be used to provide error handling exits. However, programs executing in 
31-bit addressing should not establish STAE or STAI recovery exits. 
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Command Processor Functions that Rely on Exit Routine Support 


The following types of command processors should use ESTAE exit routines: 


All command processors that process subcommands 


All command processors that request system resources that are not freed by 
ABEND or DETACH 


Command processors that process lists, to allow processing of other elements 
in the list if a failure occurs while processing one element in the list 


Command processors that attach subcommands should also provide an ESTAI 
exit to intercept abnormally terminating subcommand processors. 


Simple command or subcommand processors should not issue an ESTAE or an 
ESTAI if the terminal monitor program or calling command processor ESTAI 
exits provide adequate processing. 


Guidelines for ESTAE and ESTAI Exit Routines 


ESTAE and ESTAI exit routines should observe the following guidelines: 


l. 


The error handling exit routine should issue a diagnostic error message of the 
form: 


Ist level command-name ENDED DUE TO ERROR+ 
subcommand-name 


2nd level COMPLETION CODE IS xxxx 


The name supplied in the first level message is obtained from the environment 
control table, and the code supplied in the second level message is the 
completion code passed to the ESTAE or ESTAI exit from ABEND. The 
GNRLFAIL service routine may be used to issue the diagnostic error 
message, although it requires additional storage space (see guideline number 
4). 


The routine should issue these messages so that the original cause of 
abnormal termination is recorded should the error handling exit routine itself 
terminate abnormally before diagnosing the error. 


When an ABEND is intercepted, the command processor ESTAE exit routine 
should determine whether retry is to be attempted. If so, the exit routine 
should issue the diagnostic message and return, indicating via a return code 
that an ESTAE retry routine is available. If a retry is not to be attempted, 
the exit routine should return, indicating via a return code that no retry is to 
be attempted. The TMP ESTAI exit routine will issue the diagnostic 
message. (For a description of the return codes and their meanings, see 
Supervisor Services and Macro Instructions.) 
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2. The ESTAE or ESTAI routine that receives control from ABEND should 
perform all necessary steps to provide system cleanup. This cleanup should 
be performed in the ESTAE exit routine rather than in the ESTAE retry 
routine because DETACH with the ESTAE= YES operand does not allow 
the subtask to retry from an ESTAE/ESTAI exit. (The TMP issues 
DETACH with ESTAE= YES when a command processor has been 
interrupted with an attention.) 


3. The error handling exit routine should attempt to retry program execution 
when possible. If the command processor can circumvent or correct the 
condition that caused the error, the error handling routine should attempt to 
do so. In other cases, however, RETRY has no function and the command 
processor ESTAE exit should not specify the RETRY option. 


4. Storage might not be available when the ESTAE or ESTAI routine receives 
control. Any storage the routine requires should be acquired before it 
receives control, and be passed to it. 


Attention Exit Routines 


An attention exit routine should be provided by any command processor that 
accepts subcommands. Use the STAX macro instruction to specify the address of 
your attention handling routine. See “Attention Interruption Handling - The 
STAX Service Routine” for a complete discussion of the STAX macro instruction. 
Simple command processors should not issue a STAX if the TMP or the calling 
command processor STAX exits provide adequate processing. 


If you did not include the IBUF and the OBUF operands in the STAX macro 
instruction that set up the attention handling exit, use the PUTGET macro 
instruction, specifying the TERM operand, to send a mode message to the 
terminal identifying the program that was interrupted, and to obtain a line of 
input from the terminal. 


If you specify the OBUF operand on the STAX macro instruction without an 
IBUF operand, or with an IBUF length of 0, you can then use the PUTGET 
macro instruction, specifying the ATTN operand. This causes the PUTGET 
service routine to inhibit the writing of the mode messages, since a message was 
already written to the terminal from the output buffer specified in the STAX 
macro instruction. The PUTGET service routine merely returns a logical line of 
input from the terminal. 


In either of the above cases, if the user enters a question mark, the PUTGET 
service routine automatically causes the second level informational message chain 
(if one exists) to be written to the terminal, puts out the mode message again, and 
returns a line from the terminal. 


If you used the IBUF operand on the STAX macro instruction note that no 
logical line processing or question mark processing is performed. If the user 
returns a question mark, you will have to use the PUTLINE macro instruction to 
write the second level informational message chain to the terminal. Then issue a 
PUTGET macro instruction, specifying the TERM operand, to write a mode 
message to the terminal and to return a line of input from the terminal. 
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Whether you use the IBUF operand on the STAX macro instruction or the 
PUTGET macro instruction to return a line from the terminal, you can use the : 
command scan service routine to determine what the user has entered. JZ 


If the user enters a null line, the attention handling routine should return to the 
point of interruption. Note that, with the exception of the TPUT ASID buffers 
for TCAM, the TGET, TPG, and TPUT buffers are flushed during attention 
interruption processing. If any data was present in these buffers, it is lost. 


If a new command or subcommand is entered, the attention handling routine 
should: 


@ Post the command processor’s event control block to cause active service 
routines to return to the command processor. 


e Exit. 


e@ Reset the input stack in the command processor mainline. (A stack flush in 
an attention routine may cause severe errors.) 


The HELP Data Set 


A terminal user can enter the HELP command to retrieve information about 

commands or subcommands. This information is stored in a data set labeled 

SYS1.HELP (the HELP data set). If you add command processors to TSO, you 
should either add HELP information to the SYS1.HELP data set, or to a private Jo 
HELP data set. 


Attributes of SYS1.HELP 


SYS1.HELP is a cataloged, partitioned data set consisting of one member named 
COMMANDS and individual members for each command in the system. The 
COMMANDS member contains a list of the commands available to the user, and 
a brief description of each. The individual members for each command are 
named with the command name, and contain more specific information about the 
command and its subcommands. The HELP information contained within any 
member of the HELP data set consists of punch-card images. The logical record 
length is therefore 80 characters. 


Format of HELP Members 


Each of the HELP members, other than the COMMANDS member, is divided 
into the following subgroups, each of which can be displayed at the terminal: 


e A subcommand list - This appears only if the command has subcommands. 


e Functional description - This provides a brief description of the function of 
the command or subcommand. 


e Syntax - This describes the syntax of the command or subcommand. ) 
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@ Message identifier description - This provides information pertaining to 
messages issued by the command or its subcommand. 


@ Operand description - This provides information on the command operands. 
It includes individual sections containing brief descriptions of each positional 
operand, and of each keyword and its parameters. 


Private HELP Data Sets 


Updating SYS1.HELP 


Writing HELP Members 


You may concatenate your data set to the SYS1.HELP data set (or vice versa). 
Concatenated data sets need not have the same attributes as the SYS1.HELP data 
set, but the first concatenated data set must have the largest block size of the 
concatenated data sets, and it must not specify a fixed block size. 


Concatenated data sets are searched in the order of concatenation. If 
SYS1.HELP and a private HELP data set have been concatenated, the first 
COMMANDS member encountered by the HELP processor is used as the list of 
available commands. Thus, if you concatenate your own HELP data set to 
SYS1.HELP, you should make additions to the COMMANDS member of 
SYS!.HELP. 


Private HELP data sets must be allocated with file name SYSHELP, either in the 
LOGON procedure or on an ALLOCATE command. When data sets are 
concatenated, the file name SYSHELP is required. If only SYS!.HELP is 
required, the file name SYSHELP would not have to be allocated. (See the 
DAIR entry code X‘24’ later in this book.) 


Use the IEBUPDTE utility program or the EDIT command to update 
SYS1.HELP. SYS1.HELP is a system data set, so it will generally require 
operator intervention when it is updated. 


To add a new member to a data set named PRIVATE.HELP using the EDIT 
command, enter: 


edit 'private.help(mbrname)' data new 
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Use the information described in Figure 3-1 when you add to SYS1.HELP or set 
up your own HELP data set. The control characters, beginning in card column 1, 
divide the data set into the subgroups previously described, and thereby permit 
the HELP command processor to select message text according to the operands 
supplied on the HELP command. (See TSO/E Command Language Reference for 
a discussion of the HELP command.) 


Control Character Purpose of Data Card 


)S 
\F 


)X 


)M 


)I membername 


))messageid 


))keyword 


= subcommandname 


This card indicates that a list of commands or subcommands follows. 


This card indicates that the functional discussion of the command or 
subcommand follows. 


This card indicates that the syntax description of the command or 
subcommand follows. 


This card indicates that message ID information follows. The information is 
only printed by the HELP command when the MSGID keyword is specified. 


In MVS/XA, this card includes additional help information in the specified 
member. The include control character, )I, can appear anywhere within a 
data set member. If the help information you plan to add is not available 
yet, you can specify the control character and later add the information. No 
error messages are issued. 


The member name can be up to eight characters in length. There must be at 
least one blank before and after the member name. 


This card indicates that information follows describing the named messageid. 
One of these control cards should be present for each message issued by the 
command. Each card contains the identifier of the message it describes. 
Message IDs can be any length and the first character must be alphabetic. 


This card indicates that the command operands and their descriptions 
follow. Positional operands must follow immediately after the )O control 
card and before the ))keyword control cards. 


This card indicates that a positional operand description follows. One of 
these control cards is required for each positional operand within the 
command. Each card contains the name of the positional operand it 
describes. 


This card indicates that information follows describing the named keyword. 
One of these control cards must be present for each keyword operand within 
the command. Each card contains the name of the keyword it describes. 


This card indicates that information follows concerning the subcommand 
named after the equal sign. One of these cards is required for each 
subcommand accepted by the command being described. Note that this card 
merely names the subcommand; it does not describe it. Describe the 
subcommand in the same manner you would describe a command. 


If the subcommand has an alias name, you may include the alias name on 
the control card, i.e. =subcommandname=subcommandalias. Note that 
no blanks may appear between the subcommand and the alias. 


Figure 3-1. Format of a HELP Data Set 
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All data cards, except the =subcommandname card, can contain additional 
information. If you include additional information on the cards, the control 
characters )S, )F, )X, )I, )O, and )P must be followed by at least one blank, and 
the control character ))keyword by at least one blank or a left parenthesis. Any 
information after the membername field on the include, )I, data card is treated as 
a comment. Use the left parenthesis when the keyword you are describing is 
followed by operands enclosed in parentheses. 


The only restrictions on data cards are that columns 72-80 are reserved for 
sequence numbers, and column one must contain a right parenthesis, an equal 
sign, or a blank. The sequence numbers are not printed when the HELP 
command is executed. 


For example, information concerning a user’s SAMPLE command, shown in 


Figure 3-2, could be formatted for entry into the HELP data set (or your own 
private help data set). 


SAMPLE | positl1 [,(posit2)][KEYWD1[ (posit3,posit4) 


Figure 3-2. An Example of a User’s SAMPLE Command Format 


The SAMPLE command has one subcommand, the EXAMPLE subcommand (see 
Figure 3-3). Both the command and the subcommand can issue messages 
IKJXX110I and IKJXX1111. 


KEYWD10 
EXAMPLE | posit10,posit11} KEYWD11] [KEYWD13(posit12) ] 


KEYWD12 


Figure 3-3. An Example of a User’s EXAMPLE Subcommand Format 
Figure 3-3 shows data cards that would present and format information about the 


SAMPLE command and EXAMPLE subcommand for inclusion in the HELP 
data set. 
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Figure 3-4. Coding Example - Including the SAMPLE Command and EXAMPLE Subcommand in the HELP Data 
Set 


If you are writing a HELP member for a user-written command, and the 


command processor wants the prompt mode HELP function to be available for 
its positional parameters and/or for those of one or more of its subcommands, do 
the following. Enter the positional parameter control character, )P, on the first 


line of each positional parameter description for the command and/or 


subcommand(s). (See “Prompt Mode HELP Function” earlier in this section.) If 
no description exists for a positional parameter, you should also supply the name 
of the positional parameter along with the information you would like displayed 
when the user requests information about the parameter. If a description exists, 
you may wish to modify it so that is does not repeat information provided by the 
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messages. This suggestion also applies to the other descriptions in the HELP 
members. Keep in mind, though, that the user can request help when not 
responding to prompt mode messages. (See “Updating Existing HELP Members” 
below for an example of how to update a HELP member for a command’s 
positional parameters.) 


Note: If you insert a )P for only some of the positional parameters for a given 
command or for a given subcommand, unpredictable results may occur when 
parse processing issues a HELP command for one of its positional parameters. 


Updating Existing HELP Members 
For various reasons, you may wish to update existing HELP members. 


To make the prompt mode HELP function available for a command’s positional 
parameters, assuming it has positional parameters, update the HELP member for 
the command in the following manner. (See “Prompt Mode HELP Function” 
earlier in this section for a description of this function and a list of the commands 
for which the function is automatically provided.) Starting in column one of the 
first line of each positional parameter description for the command, enter the 
positional parameter control character, )P. The prompt mode HELP function 
may also be active for one or more of a command’s subcommands. For a 
subcommand for which this function is active, you should also insert a )P for each 
of its positional parameter descriptions in the HELP member. (See Figure 3-4.) 


If no description exists for a positional parameter, you should also supply the 
name of the positional parameter along with the information you would like 
displayed when the user requests information about the parameter. If a 
description exists, you may wish to modify it so that it does not repeat 
information provided by the messages. This suggestion also applies to the other 
descriptions in the HELP members. Keep in mind, though, that the user can 
request help when not responding to prompt mode messages. 


Note: If you insert a )P for only some of the positional parameters for a given 
command or for a given subcommand, unpredictable results may occur when 
parse processing issues a HELP command for one of its positional parameters. 


For example, if you want to enable parse processing to generate a HELP 
command for the entryname positional parameter of the DELETE command, 
update the text of the DELETE HELP member as follows: 


)O OPERANDS 
)P 'ENTRYNAME'! 


(description of entryname) 


By updating the DELETE member accordingly, you also enable the user to 
request information about the entryname positional parameter when the user is 
not being prompted for it. (See TSO/E Command Language Reference for the 
syntax of the HELP command.) 
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Chapter 4. MVS/Extended Architecture Considerations 


This section discusses considerations for MVS/Extended Architecture, with TSO 
Extensions (TSO/E 5665-285) installed, in terms of its impact on the tasks 
documented in this manual. You should be familiar with the publications that 
describe comprehensive programming considerations for MVS/Extended 
Architecture, as well as with those that describe the routines and macros discussed 
in this manual. Henceforth, MVS/Extended Architecture is referred to as 
MVS/XA. 


Note: Interfaces for service routines and macro instructions mentioned in this 
section are covered in more detail in the sections of this manual describing the 
individual service routines and macro instructions. 


31-Bit Addressing - General Interface Considerations 


The interfaces described in this section reflect what is possible on an MVS/XA 
system. When determining the attributes and linkage conventions for a program, 
you should analyze the program’s individual interfaces and its overall interactions 
with other programs. This section provides general guidelines for making these 
determinations. 


MVS/XA requires that addressing modes and program residency be considered 
when determining linkage conventions. See “Specific Interfaces and Functions” 
later in this section for brief descriptions of those considerations for the service 
routines and macro instructions described in this manual. 


Assuming you are running programs on an MVS/XA system, you might want to 
take advantage of the added virtual storage provided by extended addressing, or 
you might want to prepare for doing so in the future. Before describing linkage 
considerations, it is important to note that if a program is to be run on MVS/370 
systems or on both MVS/370 and MVS/XA systems, it cannot perform any 
functions unique to MVS/XA. 


Some MVS/XA macro instructions are downward incompatible; their MVS/XA 
expansions do not function correctly in MVS/370. Of the macros discussed in this 
manual, ATTACH, ESTAE, FESTAE, and STAX are downward incompatible. 
For a description of how to generate the desired level of a macro instruction, refer 
to SPL: System Macros and Facilities. 
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When making linkage decisions, you should analyze: 


@ Who passes control to whom J 
@ Whether return is desired 
e AMODE and RMODE attributes 


The first two items are discussed in SPL: 31-Bit Addressing. 


The following discussion provides a general description of AMODE and RMODE 
attributes; it does not attempt to cover AMODE and RMODE considerations in 
depth. For a detailed discussion of 31-bit addressing, refer to SPL: 31-Bit 
Addressing. 


The following paragraphs pertain to programs running exclusively in 370-XA 
mode. 


AMODE= 24, RMODE= 24 


Programs with these attributes expect to (or are designed to) receive control in 
24-bit addressing mode, and are loaded below 16 Mb in virtual storage. 


If you do not assign AMODE and RMODE attributes to a program, the 

attributes default to AMODE= 24 and RMODE=24. Most IBM-supplied 

command processors have these attributes and are loaded below 16 Mb in virtual 

storage. The EXEC and ALLOCATE command processors have AMODE = 31 

and RMODE=ANY attributes; these two command processors, and the 

IBM-supplied terminal monitor program, are loaded above 16 Mb. The TEST J 
command processor has AMODE=31 and RMODE= 24 attributes, and is loaded 

below 16 Mb. 


AMODE= ANY, RMODE= 724 


AMODE=ANY indicates that a program expects to (or is designed to) receive 
control in the addressing mode of the program that invoked it. Note that a 
program with the AMODE=ANY attribute may have to switch addressing 
modes for certain processing. However, such a program must switch back to the 
addressing mode in which it received control before returning to the caller. 


AMODE=ANY programs must be given the RMODE= 24 attribute. 


AMODE=ANY does not indicate whether the program should be passed input 
that resides below 16 Mb in virtual storage; the particular interfaces should be 
analyzed to determine where input may reside. However, a program should meet 
certain criteria in order to be assigned the AMODE=ANY attribute. Refer to 
SPL: 31-Bit Addressing for a description of the criteria. 
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AMODE=31 


C AMODE=31 indicates that a program expects to (or is designed to) receive 
control in 31-bit addressing mode. Such a program may have the RMODE=24 
or RMODE=ANY attribute, depending on its residency requirements. 
Regardless of the program’s RMODE attribute, the residency of its input depends 
on the program’s requirements. The program may require that some of its input 
resides below 16 Mb in virtual storage, while other input may reside anywhere. 


A program that runs exclusively in 31-bit addressing mode (AMODE= 31) may 
do so provided it complies with the restrictions of invoking, and being invoked 
by, programs that run in 24-bit addressing mode (AMODE = 24 or 
AMODE=ANY). 


Refer to SPL: 31-Bit Addressing for more information on the AMODE=31 
attribute. 


Specific Interfaces and Functions 


The interfaces described in this section reflect what is possible on an MVS/XA 
system. When determining the attributes and linkage conventions for a program, 
you should analyze both the program’s individual interfaces and its overall 
interactions with other programs. This section provides specific guidelines for 
making these determinations. 


YY Control Program Interfaces 


| Most of the IBM-supplied command processors are loaded below 16 Mb and 

| receive control in 24-bit addressing mode. The EXEC and ALLOCATE 

| command processors are loaded above 16 Mb and receive control in 31-bit 

| addressing mode. The TEST command processor is loaded below 16 Mb and 

| receives control in 31-bit addressing mode. Refer to “Testing a Newly-Written 
TMP or CP -- The TEST Command” for additional information on the TEST 
command and its services. 


The command processor parameter list (CPPL) passed by IBM-supplied control 
programs resides below 16-Mb in virtual storage. 


User-written TMPs and CPs may execute in either 24- or 31-bit addressing mode 
provided they follow the restrictions involved in invoking programs that have 
24-bit dependencies. When assigned the AMODE=31 attribute, they may be 
| loaded above 16 Mb in virtual storage (RMODE=ANY), and passed input that 
| resides above 16 Mb. The IBM-supplied TMP is loaded above 16 Mb. 
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Service Routine Interfaces 


The data type processor (IKJEBEPS) and the STA interface routine (IKJEHSIR) 
must be invoked in 24-bit addressing mode. All input passed to these two 
routines must reside below 16 Mb in virtual storage. 


If a program running in 31-bit addressing mode invokes one of these two routines, 
the LINK macro should be used to invoke it because LINK does not require the 
invoking program to switch to 24-bit addressing mode. In this case, LINK 
switches to 24-bit mode on behalf of the invoking program. If a program is 
loaded above 16 Mb in virtual storage, it must use LINK to invoke IKJEBEPS or 
IKJEHSIR. 


The following service routines can be invoked in either 24- or 31-bit addressing 
mode, but all input passed to these routines must reside below 16 Mb in virtual 
storage. These routines execute in 24-bit addressing mode and return control in 
the same addressing mode in which they are invoked: 


IKJEHCIR Catalog information routine 
IKJEHDEF Default service routine 


The following service routines can be invoked in either 24- or 31-bit addressing 
mode. When invoked in 31-bit addressing mode, these routines may be passed 
input that resides above 16 Mb in virtual storage. These routines execute and 
return control in the same addressing mode in which they are invoked: 


IKJDAIR Dynamic allocation interface routine 
IKJEFF18 §DAIRFAIL 

IKJEFF19 GNRLFAIL/VSAMFAIL 
IKJEFTSR TSO service routine 


The following service routines can be invoked in either 24-bit or 31-bit addressing 
mode. They execute in 31-bit addressing mode and can accept input above or 
below 16 Mb in virtual storage. These routines will return control in the same 
addressing mode in which they are invoked: 


IKJEFFO2 TSO message issuer routine 
IKJGETL GETLINE service routine 
IKJPARS Parse service routine 
IKJPTGT PUTGET service routine 
IKJPUTL PUTLINE service routine 
IKJSCAN Command scan service routine 
IKJSTCK STACK service routine 
IKJCT441 CLIST variable access routine 


Note that the list source descriptor (LSD) must reside below 16 Mb in virtual 
storage. The output line descriptor (OLD) can reside above 16 Mb. 


STAX (specify terminal attention exit routine) may be invoked in either 24- or 
31-bit addressing mode. Refer to “Attention Interruption Handling -- The STAX 
Service Routine” for more information. 


Refer to “Passing Control to the TSO Service Routines” later in this book for 
more detailed descriptions of interfacing with the routines listed in this section. 
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Macro Interfaces 


Figure 4-1 shows the MVS/Extended Architecture rules for the macros discussed 


in this manual. 


Note: In Figure 4-1, a dash (-) indicates that the category does not apply to the 


macro because the macro does not generate executable code. The addressing 


mode of the program that accesses the data generated by the macro must agree 


with the residence of the data. 
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Figure 4-1 (Part 1 of 2). MVS/XA Interface Rules for Macro Instructions 
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Figure 4-1 (Part 2 of 2). MVS/XA Interface Rules for Macro Instructions 


Notes on Figure 4-1 


ATTACH, LINK, LOAD, XCTL 
A program may issue the ATTACH, LINK, LOAD, and XCTL macro 
instructions while executing in either 24- or 31-bit addressing mode. These 
system services determine where to load the requested program in storage 
and in which addressing mode to invoke it based on the program’s AMODE 
and RMODE attributes. Note that LOAD only loads a program; it does J 
not invoke it. LOAD returns the address of the loaded program. The 
high-order bit of this address reflects the AMODE attribute of the loaded 
program. 


If a program is invoked via a LINK, ATTACH, or XCTL macro, it receives 
control in the addressing mode specified or allowed by its AMODE 
attribute. On the other hand, if a program branches to another program 
without changing addressing modes via the BASSM or BSM branch 
instructions, the requested program receives control in whatever addressing 
mode is active at the time of the branch -- that is, in the addressing mode of 
the caller. 


For more information on these macros, refer to System Macros and 
Facilities. 


CALL 
You may use the CALL macro to invoke a program if that program may be 
invoked in the current addressing mode. 


CALLTSSR 
The CALLTSSR macro instruction may be issued in either 24- or 31-bit 
addressing mode. See “Passing Control to the TSO Service Routines” later 
in this book for more information on issuing the CALLTSSR macro. 


2 
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ESTAE, FESTAE, STAE, ESTAI 
The ESTAE and FESTAE macros may be issued in either 24- or 31-bit 
addressing mode. Refer to “ESTAE/ESTAI Exit Routines -- Intercepting 
an ABEND” for more information. Use of the STAE macro and the 
ESTAI operand on the ATTACH macro to establish recovery exits and 
routines is not recommended. If they are used, the recovery exits and 
routines must receive control in 24-bit addressing mode -- that is, the STAE 
and ATTACH macros must be issued in 24-bit addressing mode. 


ESTAI 
See ESTAE. 


FESTAE 
See ESTAE. 


GETLINE, PUTGET, PUTLINE, STACK 
The GETLINE, PUTGET, PUTLINE, and STACK macros can be issued 
in either 24-bit or 31-bit addressing mode. These routines execute in 31-bit 
addressing mode and return control in the same addressing mode in which 
they are invoked. Input passed to these routines can reside above or below 
16 Mb in virtual storage. However, if you use the STACK macro, the list 
source descriptor (LSD) must reside below 16 Mb. 


IKJTSMSG 
The IKJTSMSG macro may be issued by a program loaded below or above 
16 Mb in virtual storage. Refer to “Message Handling” for a description of 


the standard and extended formats of the input parameter list for 
IKJEFF02. 


LINK 
See ATTACH. 


LOAD 
See ATTACH. 


Parse Macros 
If the parse service routine is invoked in 31-bit addressing mode, the parse 
parameter list, mapped by IKJPPL, can reside above 16 Mb in virtual 
storage and the parse macro instructions may be issued by a program 
loaded above 16 Mb. See Figure 4-1 for a list of the parse macros and their 
linkage requirements. The IKJRLSA parse macro may be issued in either 
24- or 31-bit addressing mode. 


PUTGET 
See GETLINE. 


PUTLINE 
See GETLINE. 


SAM Macros 


The sequential access method (SAM) terminal macro instructions must be 
issued in 24-bit addressing mode. 
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STACK 
See GETLINE. 


STAE 
See ESTAE. 


STAX 
A program may issue the STAX macro in either 24- or 31-bit addressing 
mode. Refer to “Specifying a Terminal Attention Exit -- The STAX Macro 
Instruction” for specific restrictions. 


SVC 93 (TGET, TPUT, TPG) 
SVC93 (TGET, TPUT, and TPG macros) executes in 24-bit addressing 
mode. All input passed to SVC93 must reside below 16 Mb in virtual 
storage. Programs can invoke TGET, TPUT, and TPG in 24-bit or 31-bit 
addressing mode. 


SVC 94 (Terminal Control Macros) 
SVC 94 (terminal control macros) executes in 24-bit addressing mode. With 
a few exceptions, terminal control macros must be issued in 24-bit 
addressing mode. The exceptions are the GTSIZE, RTAUTOPT, 
SPAUTOPT, and STAUTOCP terminal control macros, which may be 
issued in 31-bit addressing mode. See Figure 4-1 for a list of the terminal 
control macros and their linkage requirements. 


TGET, TPUT, TPG 
See SVC 93. 


Terminal Control Macros 
See SVC 94. 


XCTL 
See ATTACH. 


31-Bit Indirection Symbol 


When the EXTENDED keyword is specified on the IKJPOSIT parse macro 
instruction, parse accepts addresses above 16 Mb in virtual storage and allows the 
use of the 31-bit indirection symbol, ?, in indirect addresses and in address 
expressions. Refer to “Using the Parse Service Routine (IKJPARS)” for more 
information. 
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| Chapter 5. Invoking Other Programs, Commands, or CLISTs with 
| the TSO Service Routine 


| The TSO service routine allows a TSO user to invoke a command, program, or 

| CLIST from an unauthorized environment. The invoked program, command, or 

| CLIST can then be processed as if it was invoked from an authorized 
environment. Any unauthorized program or command processor that uses the 
TSO service routine can ignore the consideration of authorized or unauthorized 
environments and programs. However, an authorized program or command 
processor can use the TSO service routine to invoke only authorized programs, 

| command processors, or CLISTs consisting of only authorized command 

| processors and programs. A command processor or program can invoke the TSO 
service facility in both foreground and background TSO sessions. 
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TSO Service Routine 


Application TSO Program or 
Program Service Command 
Routine 


6 or 7 parameters 4 parameters 


Storage pointed to by parameters passed to the TSO 
service routine from the application program. 


function buffer 


TSO service routine 
reason code or function 
abend reason code 


Abend code 


Figure 5-1. TSO Service Routine 


Note: The seven parameters in this figure do not have to be contiguous to each 
other in storage. 
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C | Program Interface to TSO Commands, Programs, and CLISTs 


The program interface to TSO commands, programs, or CLISTs allows an 
unauthorized TSO program or command processor to invoke any TSO command, 
program, or CLIST, regardless of whether or not the invoked function is 
authorized. As a result, you can invoke the full range of TSO services from your 
programs without compromising MVS system integrity. For example, an 
applications program written in PLI, COBOL, assembler, or any of the other 
IBM supported programming languages can use the interface, IKJEFTSR (alias 
name, TSOLNK), to invoke the ALLOCATE command (or a CLIST containing 
multiple ALLOCATE commands) to dynamically allocate data sets. 


Note: See Chapter 6, “Program Access to CLIST Variables” for information 
about saving command output lines in a non-CLIST program. 


Invoking the TSO Service Routine 


IKJEFTSR is invoked according to the rules of the applications programming 
language in use. The following example (Figure 5-2) shows an assembler 
applications program invoking a TSO command. If a program is invoked instead 
of a command, a seventh parameter may be used to pass parameters to the 
invoked program. For more examples, see the TSO Extensions User's Guide. 
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R14,R12,12(R13) 
R12,0 

*,R12 

R13 ,SAVEAREA+4 
R11,SAVEAREA 
R11,8(,R13) 

R13 ,SAVEAREA 


OH 


R15,CVTPTR ESTABLISH 
R15,CVTTVT(,R15) ADDRESSABILITY TO THE 
R15,TSVTASF-TSVT(,R15) TSO SERVICE ROUTINE 


INVOKE THE TSO SERVICE ROUTINE -- EXECUTE LISTBC COMMAND 


CALL (15),(FLAGS,CMDBUF,BUFLEN,RETCODE,RSNCODE,ABNDCODE) , VL 
LTR R15,R15 CHECK TSR RETURN CODE 

BNZ  ERRORRTN BAD RETURN CODE FROM TSR 

CLC  RETCODE,ZERO CHECK COMMAND PROCESSOR ERROR 

BH ERRORCMD BAD RETURN CODE FORM COMMAND 

B ENDUP NO ERROR --- EXIT 

DS OH 


ANALYZE TSO SERVICE ROUTINE ERROR 


ENDUP 
ERRORCMD OH 
* 


* ANALYZE COMMAND PROCESSOR ERROR 


OH 
R13,4(,R13) 
R14,R12,12(R13) 
R15,R15 

R14 


Figure 5-2 (Part 1 of 2). Invoking an Authorized Command Using IKJEFTSR 
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C 


. DATA AREAS 
* 
ZERO Dc F'Q! 
FLAGS DS OF 
RESFLAGS DC H'O! 
ABFLAGS DC X'O1' 
FNCFLAGS DC X'O1' 
* 
CMDBUF DC C'LISTBC' 
* 
BUFLEN DC F'6! 
RETCODE DS F 
RSNCODE DS F 
ABNDCODE DS F 
SAVEAREA DS 18F 


CVTPTR EQU. 16 
CVTTVT EQU  xX'9C' 


R15 


Figure 


EQU 15 
EQU 14 
EQU 13 
EQU 12 
EQU 11 
EQU 9 

EQU 8 

IKJTSVT 

END 


ZERO 
MAPS 
FLAG 
DUMP 
TELL 


NAME 


CONSTANT 

FIRST PARM TO IKJEFTSR 
WORD 

IF ABEND OCCURS 

TSR TO EXECUTE THE COMMAND 


OF COMMAND TO BE EXECUTED 


LENGTH OF COMMAND BUFFER 
RETURN CODE FROM COMMAND 
REASON CODE 
ABEND CODE 


SAVE 


AREA 
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Notes: 


I. The syntax of the seven parameters must follow the conventions of the 
applications language being used. 


2. The seventh parameter is optional and can only be used when invoking a 
program. 


TSO Service Routine Parameters 


The seven parameters serve the following function: 


1. This parameter identifies a full word of flags. 


a. 


b. 
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Bytes one and two are zeros. 


Byte three is the error processing flag byte. It contains one of the 


following: 


e X‘00’ to show that no dump should be taken in case of an ABEND. 
e X‘01’ to show that a dump should be taken in case of an ABEND. 
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c. Byte four is the function flag byte. It contains one of the following: 


e X‘0l’ to show that a TSO command is being invoked. J 
X‘02’ to show that a program is being invoked. 
e X‘05’ to show that the function being requested is to be invoked first 

as a command and then, if the command cannot be found, as a 

CLIST. 


2. The second parameter identifies the function buffer, which contains the name 
of the command, program, or CLIST being invoked. 


Note: CLISTs can be invoked explicitly and implicitly. For more details, 
refer to CLISTs: Implementation and Reference. 


3. The third parameter contains the length of the function buffer (parameter 2). 


4. The fourth parameter identifies the function return code. The function 
return code is the return code found in register 15 when the requested 
program or command completes. 


Note: See Figure 5-3 for an explanation of the IKJEFTSR return codes. 


5. The fifth parameter identifies the function abend reason code or the TSO 
Service Routine reason code. If the TSO Service Routine has a return code of 
12 in register 15, this field contains a reason code that is associated with the 
abend code pointed to by parameter 6. If the TSO Service Routine return 
code is 20, this field indicates an error in the IKJEFTSR parameter list. J 


Note: See Figure 5-4 for an explanation of the IKJEFTSR reason codes. 


6. The sixth parameter identifies a field to contain the ABEND code, if the 
requested program or command ends unsuccessfully. 


7. The seventh parameter identifies the function parameter list. This parameter 
is optional, and can only be coded when a program (not a TSO command) is 
being invoked. This parameter list is a variable length list and the high order 
bit of the last address must be on to indicate the end of the list. 


The function parameter list: 


a. Must have 1 to 4 parameters 
b. The high order bit of the last parameter must be on 
c. Parameters 1-3 


1) A half word contains the parameter length in binary bytes, 
immediately followed by 


2) A variable length data string 
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d. The last parameter 


1) A full word containing 2 bytes of binary zeros, immediately followed 
by 


2) Two bytes containing the binary number of full words of data, 
immediately followed by 


3) A variable length data string 


The exact format of this parameter list will vary depending on the program 
being invoked. 


The invoked function (program, command, or CLIST) had a non-zero return 
code in register 15. When the invoked function completes processing, the 

function return code field pointed to by the 4th parameter contains the contents 
of register 15. 


The invoked function (program, command, or CLIST) was terminated because 
of an attention. If the invoked function was a CLIST, the CLIST did not 
contain a CLIST attention routine. If the applications programmer wishes to 
notify the end user his application program should issue a message. 


The invoked function (program, command, or CLIST) abended. The abend code 
field pointed to by the 6th parameter contains the abend code. The reason code 
field pointed to by the Sth parameter contains the reason code associated with 
the abend. 


One of the first 6 parameters in the parameter list contains addresses of data in 


eS IKJEFTSR and the requested program, command, or CLIST completed 
a protected storage. 


successfully 
20 The IKJEFTSR parameter list contains an error. The reason code field pointed 
to by the Sth parameter contains the reason code associated with the error. 
The TSO routines associated with IKJEFTSR encountered an unexpected failure. 


28 The invoker of IKJEFTSR has AMODE 24, and the parameter list contains 
31-bit addresses. (MVS/XA only) 


Figure 5-3. IKJEFTSR Return Codes 
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The length of the parameter list was invalid. 


J 


One of the following is true: 


@ The high order bit of the last parameter must be on to indicate 
the end of the list. 


@ The high order bit is on in any of the first five parameters. 


@ More than seven parameters are coded. 


The reserved flags (bytes 1 and 2) of the function (program, command, or 
CLIST) flag field pointed to by the first parameter are non-zero. 


The function (program, command, or CLIST) flag byte (byte 4) of the flag field 


pointed to by the first parameter was invalid. It should contain a decimal one 
for a command, a decimal two for a program, or a decimal five for a CLIST. 


The function (program, command, or CLIST) flag byte (byte 4) of the flag field 
pointed to by the first parameter specified a command (contained a decimal one). 
However, a seventh parameter (program parameter list) was also coded. The 

seventh parameter can only be coded for the program function. 


20 The abend processing flag byte is invalid. This byte (byte 3) of the flag field 
pointed to by the first parameter should contain either a decimal zero to request 


a dump, or a decimal one to indicate no dump is to be taken. 
24 IKJEFTSR was invoked from a non-TSO environment. This service can only be 
used in a TSO (foreground or background) environment. 


2 The function buffer length is invalid. The function buffer pointed to by the 2nd 
parameter must be greater than zero and less than 32K-5. 


8 
32 The program parameter list( pointed to by the seventh parameter of the TSO 
service routine parameter list) either resides in protected storage or contained 
addresses of data in protected storage. 


The program parameter list pointed to by the 7th parameter is invalid. The 
function parameter list: 


a. Must have | to 4 parameters 


b. The high order bit of the last parameter must be on 


c. Parameters 1-3 


(1) A half word contains the parameter length in binary bytes, 
immediately followed by 


2) A variable length data string 


d. The last parameter 


(1) A full word containing 2 bytes of binary zeros, immediately 
followed by 


(2) 2 bytes containing the binary number of full words of data, 
immediately followed by 


(3) A variable length data string 


The requested function (program, command or CLIST) was not found. 


44 IKJSCAN detected a syntax error in the function (program or command) name. 


A command began with ‘%’, but CLIST processing through the TSO service 
facility was not requested through the first parameter. 


52 Unsupported background function (program, command, or CLIST). 

56 The function (program, command, or CLIST) is authorized, but a copy of the 
function could not be found in an authorized library. 
The function (program or command) is authorized, but the requested function 
was unauthorized. 


Figure 5-4. IKJEFTSR Reason Codes 


For further information about the TSO service routine see Terminal Monitor 
Program and Service Routines Logic. 
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Chapter 6. Program Access to CLIST Variables 


This service allows any application program to examine and manipulate CLIST 
variables. Programs can access CLIST variables by calling or linking to the 
CLIST variable access module (IKJCT441). 


IKJCT441 provides the following functions: 


e@ Update or create a CLIST variable value. If the variable does not exist, 
IKJCT441 creates it. 


@ Update a CLIST variable. If the variable does not exist, IKJCT441 does not 
create it. 


@ Return a CLIST variable value. If a caller requests to return the value for a 
variable that does not exist, IKJCT441 creates it. 


@e Return all active CLIST variables and their values. 


Some CLIST variables are called control variables. Control variables are 
variables that have a special meaning in a CLIST. Generally, they provide 
information about the environment during CLIST execution. You can change or 
assign values to only some of these control variables. See TSO Extensions 
CLISTs: Implementation and Reference for a list of the control variables that you 
can modify and a list of the control variables that you cannot modify. 


Note: To save command output lines in a non-CLIST program, use IKJCT441 
to reset &SYSOUTLINE to zero for each TSO command. &SYSOUTLINE is a 
control variable that saves TSO command output and allows a CLIST or 
application to display the output. See TSO Extensions CLISTs: Implementation 
and Reference for more information about &SYSOUTLINE. 


Figure 6-1 shows how to obtain the address of IKJCT441 from the TSO vector 
table (TSVT). The figure also shows the caller’s parameter list. 
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TSVT 


TSVTVACC 


IKJCT441 


Register 1 


Caller’s parameter list 


Pointer to address 

of the variable name 

Pointer to the length 

of the variable name 

Pointer to the address 

of the variable value 

Pointer to the length of \ 
the variable value 


Pointer to TOKEN 


Figure 6-1. Program Access to CLIST Variables 


The parameter list allows callers to send input to and receive output from 
IKJCT441. The symbolic names and descriptions of the caller’s parameters 
follow: 


Parameter Function 


ECODE Entry code. The entry code is a number that indicates to IKJCT441 the function that is 
being requested. It is a constant located in the TSVT. 


NAMEPTR Address of the variable name. 

NAMELEN Length of the variable name. 

VALUEPTR Address of the variable value. 

VALUELEN Length of the variable value. 

TOKEN Used only when finding all active CLIST variables. It contains zero or the address of an 
internal CLIST control variable that points to the last variable the caller received. The 


caller must turn on the high-order bit of this parameter to indicate that it is the last 
parameter in the list. 


In MVS/XA, callers executing in 31-bit addressing mode can pass data residing i. 
above 16 Mb in virtual storage as input to IKJCT441. J 
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Update or Create a CLIST Variable Value 
C Before invoking IKJCT441 to update or create a variable, the caller: 
e Must specify each of the parameters in the parameter list. 
e Set the value of TOKEN to zero. 
e Turn on the high-order bit of the sixth word of the parameter list. 


Figure 6-2 shows an example of how to invoke IKJCT441 to update a variable 
value or create that variable if it does not exist. 
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SETS CSECT 
CVTPTR EQU. 16 
CVTTVT EQU x'9C! 


R15 EQU 15 
R14 EQU 14 
R13 EQU 13 
R12 EQU 12 
R11 EQU 11 
ROO EQU 0 
IKJTSVT 
SETS CSECT 


STM R14,R12,12(R13) 
BALR R12,0 

USING *,R12 

ST R13 ,SAVEAREA+4 
LA R15 ,SAVEAREA 
ST R15,8(,R13) 

LA R13,SAVEAREA 


SAVE CALLER'S REGISTERS 

ESTABLISH ADDRESSABILITY 

BASE REGISTER OF EXECUTING PROGRAM 
CALLER'S SAVEAREA ADDRESS 

EXECUTING PROGRAM'S SAVEAREA ADDRESS 
EXECUTING PROGRAM'S SAVEAREA ADDRESS 
EXECUTING PROGRAM'S SAVEAREA ADDRESS 


L R15,CVTPTR ACCESS THE CVT 
L R15,CVTTVT(,R15) ACCESS THE TSVT 
L R15,TSVTVACC-TSVT(,R15) ACCESS THE VARIABLE ACCESS RIN 


* 


LTR R15,R15 
BNZ CALL441 
LINK441 LINK EP=IKJCT441, 
PARAM=(ECODE, 
NAMEPTR, 
NAMELEN, 
VALUEPTR, 
VALUELEN, 
TOKEN), 
VL=1 
B RET441 
CALL441 CALL (15), 
(ECODE, 
NAMEPTR, 
NAMELEN, 
VALUEPTR, 
VALUELEN, 
TOKEN), 
VL 
* 
RET441 LTR R15,R15 


BNZ ERRORRTN 
* 


* 


INVOKE THE VARIABLE ACCESS SERVICE 


VERIFY TSVT ADDRESS PRESENT 
IF PRESENT, CALL IKJCT441 


ENTRY CODE 

POINTER TO VARIABLE NAME 

LENGTH OF VARIABLE NAME 

POINTER TO VARIABLE VALUE 

LENGTH OF VARIABLE VALUE 

TOKEN TO VARIABLE ACCESS SERVICE 
CAUSES HI BIT ON IN THE PARM LIST 


ENTRY CODE 

POINTER TO VARIABLE NAME 

LENGTH OF VARIABLE NAME 

POINTER TO VARIABLE VALUE 

LENGTH OF VARIABLE VALUE 

TOKEN TO VARIABLE ACCESS SERVICE 
CAUSES HI BIT ON IN THE PARM LIST 


CHECK RETURN CODE 


Figure 6-2 (Part 1 of 2). Update or Create a CLIST Variable Value 
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t+ t+ +£ + + & 


+ + + + + HH 


ERRORRTN 


NAME 
NAMELEN 
VALUE 
VALUELEN 
NAMEPTR 
VALUEPTR 
TOKEN 
ECODE 
SAVEAREA 


DS 
L 
L 
LM 
BR 


OH 

R13 
R14 
ROO 
R14 


,4(,R13) CALLER'S SAVEAREA 

,12(,R13) RESTORE REGISTER 14 

,R12,20(R13) RESTORE REMAINING REGISTERS 
RETURN TO CALLER, REGISTER 15 CONTAINS 
THE RETURN CODE FROM IKJCT441 


CL12'VARIABLENAME' NAME OF THE VARIABLE 

BY" LENGTH OF THE VARIABLE NAME 
CL3'YES' VARIABLE VALUE 

Ett LENGTH OF THE VARIABLE VALUE 
A (NAME ) POINTER TO THE VARIABLE NAME 
A(VALUE) POINTER TO THE VARIABLE VALUE 
F'Q' TOKEN (UNUSED HERE) 
A(TSVEUPDT) ENTRY CODE FOR SETTING VALUES 
18F 


Figure 6-2 (Part 2 of 2). 


Update or Create a CLIST Variable Value 


IKJCT441 places one of the following return codes in register 15, but does not 
change any of the parameters in the caller’s parameter list. 


Content Meaning 

0 IKJCT441 updated or created the variable. 

12 The variable is a label, and IKJCT441 did not update it. 

16 The variable is a CLIST built in function or a control variable that the user cannot 


modify, such as &SYSDATE, and IKJCT441 did not update it. 


32 A storage management (GETMAIN/FREEMAIN) failure occurred. 

36 The length of the variable name is less than 1 or greater than 252, or the length of the 
value of a symbolic variable is less than 1 or greater than 32,678. 

40 The caller’s parameter list contains an error, or the caller is not in a CLIST environment. 

44 The entry code is not valid. 


Update a CLIST Variable Value Only 


Before invoking IKJCT441 to update a variable, the caller: 


e Must specify each of the parameters in the parameter list. 
e Set the value of TOKEN to zero. 
e Turn on the high-order bit of the sixth word of the parameter list. 


Figure 6-3 shows an example of how to invoke IKJCT441 to update a variable 


value. If the variable does not exist, IKJCT441 does not create it, but returns to 
the caller with a return code of X‘52’. 
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NOIMPM 
CVTPTR 
CVTTVT 
ROO 


+ 


LINK441 


CALL441 


* 
RET441 


* 
* 


ERRORRTN 


+ + + 


Figure 6-3 (Part 1 of 2). 
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CSECT 
EQU 16 

EQU  x'9C! 

EQU 0 

EQU 8 

EQU 11 

EQU 12 

EQU 13 

EQU 14 

EQU 15 

IKITSVT 

CSECT 

STM R14,R12,12(R13) 
BALR R12,0 

USING *,R12 

ST R13,SAVEAREA+4 
LA R15, SAVEAREA 
ST R15,8(,R13) 

LA R13,SAVEAREA 

if R15,CVTPTR 

L R15,CVTTVT(,R15) 
i 


SAVE CALLER'S REGISTERS 

ESTABLISH ADDRESSABILITY 

BASE REGISTER OF EXECUTING PROGRAM 
CALLER'S SAVEAREA ADDRESS 

EXECUTING PROGRAM'S SAVEAREA ADDRESS 
EXECUTING PROGRAM'S SAVEAREA ADDRESS 
EXECUTING PROGRAM'S SAVEAREA ADDRESS 


ACCESS THE CVT 
ACCESS THE TSVT 


R15,TSVTVACC-TSVT(,R15) ACCESS THE VARIABLE ACCESS RTN 


INVOKE THE VARIABLE ACCESS SERVICE 


LTR 
BNZ 
LINK 


CALL 


R15,R15 
CALL441 
EP=IKJCT441, 
PARAM=(ECODE, 
NAMEPTR, 
NAMELEN, 
VALUEPTR, 
VALUELEN, 
TOKEN), 
VL=1 

RET441 

(15), 
(ECODE, 
NAMEPTR, 
NAMELEN, 
VALUEPTR, 
VALUELEN, 
TOKEN), 

VL 


R15,R15 
ERRORRTN 


OH 

RO8 , TSVRUNDF 
R15,RO08 
EXITCODE 


VERIFY TSVT ADDRESS PRESENT 
IF PRESENT, CALL IKJCT441 


ENTRY CODE 

POINTER TO VARIABLE NAME 

LENGTH OF VARIABLE NAME 

POINTER TO VARIABLE VALUE 

LENGTH OF VARIABLE VALUE 

TOKEN TO VARIABLE ACCESS SERVICE 
CAUSES HI BIT ON IN THE PARM LIST 


ENTRY CODE 

POINTER TO VARIABLE NAME 

LENGTH OF VARIABLE NAME 

POINTER TO VARIABLE VALUE 

LENGTH OF VARIABLE VALUE 

TOKEN TO VARIABLE ACCESS SERVICE 
CAUSES HI BIT ON IN THE PARM LIST 


CHECK RETURN CODE 


OBTAIN NO IMPLICIT RETURN CODE 
DETERMINE IF UNDEFINED VARIABLE 
IF NOT, THEN EXIT 


ISSUE ERROR MESSAGES OR TAKE ANY APPROPRIATE ACTION 


Update a CLIST Variable Value Only 


+ + + + + * 


+e +e + e HF F 


EXITCODE L R13,4(,R13) CALLER'S SAVEAREA 
L R14,12(,R13) RESTORE REGISTER 14 
LM ROO,R12,20(R13) RESTORE REMAINING REGISTERS 
BR R14 RETURN TO CALLER, REGISTER 15 CONTAINS 
THE RETURN CODE FROM IKJCT441 


NAME CL12'VARIABLENAME' NAME OF THE VARIABLE 

NAMELEN F'12' LENGTH OF THE VARIABLE NAME 

VALUE CL3'YES' VARIABLE VALUE 

VALUELEN ee LENGTH OF THE VARIABLE VALUE 

NAMEPTR A (NAME ) POINTER TO THE VARIABLE NAME 

VALUEPTR A(VALUE ) POINTER TO THE VARIABLE VALUE 

TOKEN F'Q' TOKEN (UNUSED HERE) 

ECODE A(TSVNOIMP ) ENTRY CODE FOR NO IMPLICIT SETTING 

= OF VALUES. IF THE SYMBOLIC VARIABLE 
NAME HAD NOT BEEN PREVIOUSLY DEFINED 
IKJCT441 WILL ISSUE THE RETURN CODE 
of 52 (TSVRUNDF). 

SAVEAREA 


Figure 6-3 (Part 2 of 2). Update a CLIST Variable Value Only 


IKJCT441 places one of the following return codes in register 15, but does not 
change any of the parameters in the caller’s parameter list. 


Content Meaning 


0 IKJCT441 updated the variable. 
12 The variable is a label, and IKJCT441 did not update it. 
16 The variable is a CLIST built-in function or a control variable that the user cannot 


modify, such as &SYSDATE, and IKJCT441 did not update it. 


32 A storage management (GETMAIN/FREEMAIN) failure occurred. 

3% The length of the variable name is less than 1 or greater than 252, or the length of the 
value of a symbolic variable is less than 1 or greater than 32,678. 

40 The caller’s parameter list contains an error, or the caller is not in a CLIST environment. 

44 The entry code is not valid. 

52 The variable does not exist, and IKJCT441 did not create it. 
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Return the Value of a CLIST Variable 
Before invoking IKJCT441 to return the value of a CLIST variable, the caller: 
e Miust specify: 
— Entry code (ECODE) 
— Address of the variable name (NAMEPTR) 
— Length of the variable name (NAMELEN). 
e Set the value of TOKEN to zero. 


e Turn on the high-order bit of the sixth word of the parameter list. 


Figure 6-4 shows an example of how to invoke IKJCT441 to return the value of a 
CLIST variable. 
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é LOOK CSECT 
CVTPTR EQU_ 16 


CVTTVT EQU x'9C' 


R15 EQU 15 

R14 EQU 14 

R13 EQU 13 

R12 EQU 12 

| R11 EQU 11 
| RY EQU) 9 

R8 EQU 8 

R7 EQU 7 

RO EQU O 
IKITSVT 

LOOK CSECT 
STM R14,R12,12(R13) SAVE CALLER'S REGISTERS 
BALR R12,0 ESTABLISH ADDRESSABILITY 
USING *,R12 BASE REGISTER OF EXECUTING PROGRAM 
ST R13,SAVEAREA+4 CALLER'S SAVEAREA ADDRESS 
LA R15,SAVEAREA EXECUTING PROGRAM'S SAVEAREA ADDRESS 
ST R15,8(,R13) EXECUTING PROGRAM'S SAVEAREA ADDRESS 
LA R13,SAVEAREA EXECUTING PROGRAM'S SAVEAREA ADDRESS 

* 

* 
L R15,CVTPTR ESTABLISH 
L R15,CVTTVT(,R15) ADDRESSABILITY TO THE 
L R15,TSVTVACC-TSVT(,R15) VARIABLE ACCESS ROUTINE 


+ 


INVOKE THE VARIABLE ACCESS SERVICE 


LTR R15,R15 VERIFY TSVT ADDRESS PRESENT 
BNZ CALL441 IF PRESENT, CALL IKJCT441 
w LINK441 LINK EP=IKJCT441, * 
PARAM=(ECODE, ENTRY CODE * 
NAMEPTR, POINTER TO VARIABLE NAME * 
NAMELEN, LENGTH OF VARIABLE NAME * 
VALUEPTR, POINTER TO VARIABLE VALUE * 
VALUELEN, LENGTH OF VARIABLE VALUE * 
TOKEN), TOKEN TO VARIABLE ACCESS SERVICE * 
VL=1 CAUSES HI BIT ON IN THE PARM LIST 
B RET441 
CALL441 CALL (15), * 
(ECODE, ENTRY CODE * 
NAMEPTR, POINTER TO VARIABLE NAME * 
NAMELEN, LENGTH OF VARIABLE NAME * 
VALUEPTR, POINTER TO VARIABLE VALUE * 
VALUELEN, LENGTH OF VARIABLE VALUE * 
TOKEN), TOKEN TO VARIABLE ACCESS SERVICE * 
VL CAUSES HI BIT ON IN THE PARM LIST 


* 


RET441 LTR R15,R15 
BNZ ERRORRTN 


L R7 , VALUELEN 
L R8,VALUEPTR 
LA R9Y,L' VALUE 
CR R7,R9 
BNE BAD 
CLC O(L'VALUE,R8) , VALUE 
BNE BAD 

* 

* 

C Figure 6-4 (Part 1 of 2). Return a CLIST Variable Value 
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BAD 
ERRORRTN 
R13,4(,R13) 
R14,12(,R13) RESTORE REGISTER 14 
RO,R12,20(R13) RESTORE REMAINING REGISTERS 
R14 RETURN TO CALLER, REGISTER 15 CONTAINS 
THE RETURN CODE FROM IKJCT441 


NAME CL12'VARIABLENAME' NAME OF THE VARIABLE 

NAMELEN Et12! LENGTH OF THE VARIABLE NAME 
VALUELEN F LENGTH OF VARIABLE VALUE 
NAMEPTR A(NAME ) POINTER TO THE VARIABLE NAME 
VALUEPTR A POINTER TO THE VARIABLE VALUE 
VALUE CL3'YES' VARIABLE VALUE 

TOKEN F'Q! TOKEN (UNUSED HERE) 

ECODE A(TSVERETR) ENTRY CODE FOR RETRIEVE 
SAVEAREA 18F 


Figure 6-4 (Part 2 of 2). Return a CLIST Variable Value 


IKJCT441 returns values for the following parameters unless specified otherwise 
by the return code: 


e VALUEPTR contains the address of the value of the variable. 
e VALUELEN contains the length of the variable value. 


IKJCT441 places one of the following return codes in register 15: 
Content Meaning 
0 IKJCT441 successfully returned the variable. 


4 The caller should not rescan the variable. It is an I/O variable containing an & and is not 
a variable name. 


8 The variable is a CLIST built-in function, such as &STR, that requires evaluation. 

12 The variable is a label. IKJCT441 updated VALUEPTR and VALUELEN, but the value 
of the variable is meaningless. 

36 The length of the variable is less than 1 or greater than 252. 

40 The caller’s parameter list contains an error, or the caller is not in a CLIST environment. 


IKJCT441 did not update VALUEPTR and VALUELEN. 


44 The entry code is not valid. IKJCT441 did not update VALUEPTR and VALUELEN. 
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Return all Active CLIST Variables and their Values 


C To list all the CLIST variables and their values, the caller invokes IKJCT441 once 
for each existing CLIST variable. The caller sets TOKEN to zero before invoking 
IKJCT441 for the first time. When the value in TOKEN is zero, IKJCT441 
assumes this is the beginning of a list. Before returning to the caller, IKJCT441 
places the address of an internal CLIST control variable in TOKEN and uses this 
value on subsequent invocations to find the next variable. The caller must not 
change the value that IKJCT441 places in TOKEN. When there are no more 
variables, IKJCT441 places a zero in TOKEN and sets the appropriate return 
code. 


Before invoking IKJCT441 to find all the CLIST variables, the caller must: 
e Specify the entry code. 

e Set TOKEN to zero on the first entry. 

e Turn on the high-order bit of the sixth word of the parameter list. 


Figure 6-5 on page 6-12 shows an example of how to invoke IKJCT441 to find 
all CLIST variables and their values. 
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R15 EQU 15 
R14 EQU 14 
R13 EQU 13 
R12 EQU 12 
R11 EQU 11 
RQ EQU 9 
R8 EQU 8 
RO EQU 0 

IKITSVT 


LOCATE CSECT 
STM R14,R12,12(R13) SAVE CALLER'S REGISTERS 


BALR R12,0 ESTABLISH ADDRESSABILITY 
USING *,R12 BASE REGISTER OF EXECUTING PROGRAM 
ST R13,SAVEAREAt+4 CALLER'S SAVEAREA ADDRESS 
LA R15,SAVEAREA EXECUTING PROGRAM'S SAVEAREA ADDRESS 
ST R15,8(,R13) EXECUTING PROGRAM'S SAVEAREA ADDRESS 
LA R13,SAVEAREA EXECUTING PROGRAM'S SAVEAREA ADDRESS 
* 
* 
LOOP DS OH 
L R15,CVTPTR ESTABLISH 
L R15,CVTTVT(,R15) ADDRESSABILITY TO THE 
L R15,TSVTVACC-TSVT(,R15) VARIABLE ACCESS SERVICE 
* 
* INVOKE THE VARIABLE ACCESS SERVICE 
* 
LTR R15,R15 VERIFY TSVT ADDRESS PRESENT 
BNZ CALL441 IF PRESENT, CALL IKJCT441 
LINK441 LINK EP=IKJCT441, * 
PARAM=(ECODE, ENTRY CODE * 
NAMEPTR, POINTER TO VARIABLE NAME * 
NAMELEN, LENGTH OF VARIABLE NAME * 
VALUEPTR, POINTER TO VARIABLE VALUE * 
VALUELEN, LENGTH OF VARIABLE VALUE * 
TOKEN), TOKEN TO VARIABLE ACCESS SERVICE * 
VL=1 CAUSES HI BIT ON IN THE PARM LIST 
B RET441 
CALL441 CALL (15), = 
(ECODE, ENTRY CODE * 
NAMEPTR, POINTER TO VARIABLE NAME * 
NAMELEN, LENGTH OF VARIABLE NAME * 
VALUEPTR, POINTER TO VARIABLE VALUE * 
VALUELEN, LENGTH OF VARIABLE VALUE * 
TOKEN) , TOKEN TO VARIABLE ACCESS SERVICE * 
VL CAUSES HI BIT ON IN THE PARM LIST 
* 
RET441 Cc R15 ,NOMORE 
BE ENDUP 


LTR R15,R15 
BNZ ERRORRTN 
* 


MAINLINE OH 
R8,NAMEPTR 


R9Y,VALUEPTR 


a a 
WY 


Figure 6-5 (Part 1 of 2). Return all Active CLIST Variables and their Values 
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ISSUE 'PUTLINE' TO WRITE VARIABLE NAME AND VALUE 
- OR - 
SAVE THE NAME AND VALUE IN A TABLE 


ee ee He 


RRORRTN DS OH 


ANALYZE RETURN CODE 


* + © Ol © & & & 


B MAINLINE 


DS OH 


R13,4(,R13) 

R14,12(,R13) RESTORE REGISTER 14 

RO,R12,20(R13) RESTORE REMAINING REGISTERS 

R14 RETURN TO CALLER, REGISTER 15 CONTAINS 
THE RETURN CODE FROM IKJCT441 


NAMELEN LENGTH OF NAME WILL BE RETURNED HERE 
VALUELEN LENGTH OF VALUE WILL BE RETURNED HERE 
NAMEPTR ADDRESS OF NAME WILL BE RETURNED HERE 
VALUEPTR ADDRESS OF VALUE WILL BE RETURNED HERE 
TOKEN F'O!' TOKEN MUST BE ZERO ON THE FIRST CALL 

. AND NEVER CHANGED BY THE CALLER 
ECODE A(TSVELOC) ENTRY CODE FOR THE 'LOCATE' SERVICE 
NOMORE A(TSVRNOM) RETURN CODE FOR NO MORE NAMES 

SAVEAREA 18F 


Figure 6-5 (Part 2 of 2). Return all Active CLIST Variables and their Values 


IKJCT441 returns values for the following parameters unless specified otherwise 
by the return code: 


@ NAMEPTR contains the address of the variable name. 

@e NAMELEN contains the variable name length. 

@e VALUEPTR contains the address of the value of the variable. 
@e VALUELEN contains the variable value length. 


e TOKEN contains zero or the address of an internal CLIST control variable 
that identifies the next variable. 
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IKJCT441 places one of the following return codes in register 15: 


Content 


4 


12 


20 


Meaning 
IKJCT441 successfully updated the parameters for this variable. 


The caller should not rescan the variable. It is an I/O variable containing an & and is not 
a variable name. 


The variable requires evaluation. IKJCT441 did not update VALUEPTR and 
VALUELEN. The value of the variable is not relevant. 


The variable is a label. The value of the variable is meaningless. 
There are no more variables. 


The caller’s parameter list contains an error, or the caller is not in a CLIST environment. 
IKJCT441 did not return values for any of the parameters. 


The entry code is not valid. IKJCT441 did not return values for any of the parameters. 
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Chapter 7. Processing Terminal Requests - The TSO Service 


Routines 


The TSO service routines process terminal requests initiated by the terminal 
monitor program (TMP), command processors (CPs), and other service routines. 
If you write your own command processors, or replace the IBM-supplied terminal 
monitor program with one of your own design, you should use the service 
routines to process terminal requests. 


The TSO service routines build, modify, or make use of various control blocks. 
The following control block DSECTS are provided in SYS1.MACLIB for your 
use, and are listed in Data Areas. 


IKJCPPL 
IKJCSOA 
IKJCSPL 
IKJDAPL 
IKJDAP0C 
IKJDAP00 
IKJDAP04 
IKJDAP08 
IKJDAPIC 
IKJDAP10 
IKJDAP14 
IKJDAP18 
IKJDAP2C 
IKJDAP24 
IKJDAP28 
IKJDAP30 
IKJDAP34 
IKJDFPB 
IKJDFPL 
IKJECT 
IKJEFFDF 
IKJEFFGF 
IKJEFFMT 
IKJGTPB 
IKJIOPL 
IKJLSD 
IKJPGPB 
IKJPPL 
IKJPSCB 
IKJPTPB 
IKJSTPB 
IKJSTPL 
IKJTAIE 
IKJTAXE 
IKJTMPWA 
IKJTPL 
IKJUPT 


The command processor parameter list 

The command scan output area 

The command scan parameter list 

The dynamic allocation parameter list 
DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

DAIR entry code parameter block 

The default parameter block 

The default parameter list 

The environment control table for GETLINE/PUTLINE/PUTGET/STACK 
PARMLIST to IKJEFF18 (DAIRFAIL) 
PARMLIST to IKJEFF19 (GNRLFAIL) 
PARMLIST to IKJEFF02 

The GETLINE parameter block 

The input output parameter list for GETLINE/PUTLINE/PUTGET/STACK 
The list source descriptor for STACK 

The PUTGET parameter block 

Defines the parse parameter list 

The protected step control block 

The PUTLINE parameter block 

The STACK parameter block 

The STACK parameter list 

Terminal attention interrupt element from STAX 
Terminal attention exit element from STAX 
The terminal monitor program work area 
TEST parameter list 

User profile table 
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Interfacing with the TSO Service Routines 


When the terminal monitor program attaches a command processor, register 1 J 
contains a pointer to a command processor parameter list (CPPL) containing 

addresses required by the command processor. The CPPL is located in subpool 1. 

The control block interface between the TMP and an attached CP is shown in 

Figure 7-1. 


Terminal Command 
Monitor Processor 
Program 


ATTACH 


Register | 


Figure 7-1. Control Block Interface between the TMP and CP 


The Command Processor Parameter List 


You must pass certain addresses contained in the CPPL to the TSO service 
routines. Your user-written command processors can access the CPPL via the 
symbolic field names contained in the IKJCPPL DSECT by using the address 
received in register 1 as a starting address for the DSECT. The use of the 
DSECT is recommended since it protects the command processor from any 
changes to the CPPL. 


The command processor parameter list, as defined by the IKJCPPL DSECT, is a : 
four-word parameter list. Figure 7-2 describes the contents of the CPPL. - 
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When the TMP invokes a problem program, whether a command processor or 
not, register 1 contains the address of the CPPL. The CPPL is required by any 
program that is going to use TSO service routines. If any problem program or 
user-written command processor 1s going to invoke an IBM-supplied command 
processor, the CPPL address must be supplied in register 1. 


With the exception of the TEST command processor, which is invoked in 31-bit 
addressing mode and can be passed input above 16 Mb in virtual storage, the 
IBM-supplied command processors and TMP require that their input reside below 
16 Mb. 


User-written TMPs and CPs may pass input below or above 16 Mb in virtual 
storage, provided they adhere to the guidelines set forth in “31-Bit Addressing -- 
General Interface Considerations” earlier in this book. 


an | Contents or Meaning 


CPPLCBUF | The address of the command buffer for the currently attached command 
processor. 


CPPLUPT The address of the user profile table (UPT). The UPT is built by the 
LOGON/LOGOFF scheduler from information stored in the user 
attribute data set (UADS) and from information contained in the 
LOGON command. The address of the UPT is obtained from the 


PSCBUPT field of the protected step control block (PSCB). 


CPPLPSCB The address of the protected step control block (PSCB). The PSCB is 
built by the LOGON/LOGOFF scheduler from information stored in 
the UADS. The TMP can obtain the address of the PSCB using the 
EXTRACT macro instruction. 


CPPLECT The address of the environment control table (ECT). The ECT must be 
built by the TMP during its initialization process; it is used by the TSO 
service routines and by some TSO commands and subcommands. 


Figure 7-2. The Command Processor Parameter List (CPPL) 


Passing Control to the TSO Service Routines 


For a description of linkage and program residency considerations, refer to 
“Service Routine Interfaces” in the previous section. 


There are four ways you can. pass control to the TSO service routines. 


1. You can issue an I/O macro instruction without the ENTRY parameter for 
the I/O service routines. 


2. Youcan issue a LINK macro instruction to a service routine, but this 
requires more system overhead than other methods. 


The LINK macro instruction loads the routine in storage based on its 
RMODE attribute, and passes control to the routine in the addressing mode 
specified or allowed by its AMODE attribute. 


3. You can issue a LOAD macro instruction for a service routine and then do 


branches to the loaded routine, but this also requires more system overhead 
than other methods. 
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The LOAD macro loads the routine in storage based on its RMODE 
attribute. LOAD returns the address of the loaded program. The high-order 
bit of this address reflects the AMODE attribute of the loaded program. If 
the loaded program should not be invoked in the current addressing mode, 
the BASSM or BSM instruction may be used to set the appropriate 
addressing mode. If you use BASSM or BSM, you should ensure that the 
invoked program can return successfully. 


4. You can issue a CALLTSSR macro to generate a branch to a TSO service 
routine residing in the link pack area; if the routine does not reside in the link 
pack area, CALLTSSR generates a LINK macro instruction. 

The CALLTSSR macro applies to only the following routines: 


IKJDAIR Dynamic allocation interface routine 
IKJEFF02 TSO message issuer routine 
IKJEHCIR Catalog information routine 
IKJEHDEF Default routine 

IKJPARS Parse routine 

IKJSCAN Command scan 


A caller can invoke IKJEHCIR and IKJEHDEF in either 24- or 31-bit addressing 
mode. However, both routines execute in 24-bit addressing mode and return 
control in the caller’s addressing mode. 


IKJDAIR can be invoked, and can execute, in 24- or 31-bit addressing mode. 
When invoked in 31-bit addressing mode, IKJDAIR may be passed input that 
resides above 16 Mb in virtual storage. 


IKJEFFO2, IKJPARS, and IKJSCAN can be invoked in either 24-bit or 31-bit 
addressing mode. These routines execute in 31-bit addressing mode and can 
accept input above or below 16 Mb in virtual storage. 


Refer to the appropriate sections in this book for more information about these 
routines. 


The CALLTSSR Macro Instruction 


Figure 7-3 shows the execute form of the CALLTSSR macro instruction. There 
is no list form. Each of the operands is explained in the following figure. 
Appendix A describes the notation used to define macro instructions. 


[symbol] CALLTSSR EP=entry point name 


(register) 


fait las list address } | 


Figure 7-3. The CALLTSSR Macro Instruction 


Note: Any module that uses the CALLTSSR macro must include the CVT 
mapping macro (CVT) found in SYS1.AMODGEN. In addition, any module 
that uses IKJCAF must include the TSVT mapping macro (TSVT), also found in 
SYS1.AMODGEN. 
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J 


Example 


EP =entry point name 
Specifies one of the following names: IKJDAIR, IKJEFF02, IKJEHCIR, 
IKJEHDEF, IKJPARS, IKJCAF, IKJSCAN. 

MF=E 
Indicates that this is the execute form of the macro instruction. 


list address or (register) 


Specifies the address, or register that contains the address, of a parameter 
list to be passed to the service routine. 


This example shows how the CALLTSSR macro instruction could be used to pass 
control to the parse service routine. 


CALLTSSR EP=IKJPARS ,MF=(E,PPL) 
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| Chapter 8. Handling Messages 


Message Levels 


TSO messages are divided into three classes: 


e Prompting messages 
@e Mode messages 
e Informational messages 


Prompting messages begin with ENTER or REENTER, and require a response 
from the user. Prompting messages should be initiated by the parse service 
routine, rather than by parse validity check exits, using the text supplied by the 
command processor as the PROMPT operand of the IKJPOSIT, IKJTERM, 
IKJOPER, IKJRSVWD or IKJIDENT parse macro instructions. See “Using the 
Parse Service Routine (IKJPARS)” for a discussion of the PROMPT operand on 
these macro instructions. 


Mode messages are the READY messages sent by the terminal monitor program, 
and any other similar messages sent by command processors, such as the EDIT 
mode message sent by the EDIT command processor. They inform the user 
which command is in control and let him know that the system is waiting for him 
to enter a new command or subcommand. 


Informational messages do not require an immediate response from the user. 


Prompting and mode messages should be displayed using the PUTGET service 
routine. Informational messages should be displayed using the PUTLINE service 
routine. The TPUT routine does not support multi-level messages, message id 
stripping, and text insertion, and does not function in background mode (it acts as 
a NOP). 


Messages usually should have associated with them other messages that more fully 
explain the initial message. These messages, called second level messages, are 
displayed only if the user specifically requests them by entering a question mark 
?). 


Note that if the user uses PUTGET with TERMGET =ASIS, the user’s terminal 
will not recognize the question mark. 


Prompting messages may have any number of second level messages. Second 
level messages, if any, are displayed when the user enters a question mark in 
response to the initial message. If the user enters a question mark after all second 
level messages have been displayed, with a few exceptions (see “Prompt Mode 
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HELP Function”), parse processing generates a HELP command to give the user : 
specific information about the operand for which he is being prompted. If the J 
user enters a question mark after viewing the online usage information, the NO 
INFORMATION AVAILABLE message is issued. 


An informational message can have only one second level message associated with 
it. Since many informational messages might be displayed at the terminal before 
a question mark is returned from the terminal, PUTLINE moves all second level 
informational messages to subpool 78 and chains them off the environment 
control table. This chain exists from one PUTGET for a mode message to the 
next. In other words, whenever the user can enter a new command or 
subcommand, the user can enter a question mark instead, requesting all the 
second level messages for informational messages issued during execution of the 
previous command or subcommand. If the user does not enter a question mark, 
PUTGET deletes the second level messages and frees the storage they occupy. 


Mode messages cannot have second level messages, since a question mark entered 
in response to a mode message is defined as a request for the second levels of 
previous informational messages. Your program should request all commands or 
subcommands by issuing a mode message with the PUTGET service routine so 
that second level informational messages may be properly handled. 


Effects of the Input Source on Message Processing 


input stack is an in-storage list rather than a terminal. See the explanation of the 
STACK macro instruction for a discussion of in-storage lists. In-storage lists may 
be either procedures or source lists. 


Message handling is considerably affected if the input source designated by the ) 


If a procedure without the prompt option is being executed, the PUTGET service 
routine does not display prompting messages, but returns an error code (12) in 
register 15. If the parse service routine issued the PUTGET macro instruction, 
the parse service routine issues an informational message to the terminal, and 
returns an error code 4 to its caller. The command processor should reset the 
input stack and terminate. If a command processor issued the PUTGET macro 
instruction, the command processor should use the PUTLINE service routine to 
write an appropriate informational message to the terminal prior to terminating. 


If a source in-storage list is being processed, prompt messages are displayed to, 
and responses read from, the terminal by the PUTGET service routine. 


If the user at the terminal has specified the “PAUSE” operand on the PROFILE 
command, PUTGET issues a special message, “PAUSE,” if all of these three 
conditions exist: 


1. A mode message is to be written out. 


2. Second level messages exist. 
3. An in-storage list is being processed. 


The user may enter either a question mark or a null line. If he enters a question 4 
mark, the chain of second level messages is written to the terminal. If he enters a J 
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null line, control returns to the executing command processor. In either case, the 
next line from the in-storage list is returned to the command processor. 


A special situation arises if an in-storage list is being processed, second level 
messages are chained, and the user has specified NOPAUSE as an operand of the 
PROFILE command. Normally, if a subcommand encounters an error situation, 
it issues an informational message and returns. The command processor then uses 
the PUTGET service routine to issue a mode message on the assumption that the 
user can take corrective action with other subcommands. When processing from 
an in-storage list, this is not true. If NOPAUSE was specified, PUTGET returns 
an error code (12) to the calling routine. In most cases, the command processor 
should reset the input stack and terminate. If the message producing the second 
level message was purely informational and does not require corrective action, the 
command processor may set the ECTMSGEF flag in the environment control table 
to delete the second level message, and reissue the PUTGET macro instruction to 
continue. 


TSO Message Issuer Routine (IKJEFF02) 


The TSO message issuer routine issues a message as a PUTLINE, PUTGET, 
write-to-operator (WTO), or write-to-programmer (WTP). You may invoke 
IKJEFFO2 just to issue the message to the terminal, both to issue the message and 
return the requested message to the caller in the caller’s buffers, or just to return 
the message to the caller. This process of returning the message is referred to as 
extracting the message. This routine simplifies the issuing of messages with inserts 
because hexadecimal inserts can be converted to printable characters and the same 
parameter list used to issue any message. It also makes it more convenient to 
place all messages for a command in a single CSECT or assembly module, which 
is important when message texts must be modified. Adding or updating a 
message 1s simpler when IKJEFFO2 is used, rather than PUTLINE or PUTGET. 


Refer to “Interfacing with the TSO Service Routines” earlier in this book for a 
description of the ways in which IKJEFFO02 may be invoked. Regardless of the 
linkage method used, IKJEFFOQ2 may be invoked in either 24- or 31-bit addressing 
mode. IKJEFFO2 executes in 31-bit addressing mode and can accept input above 
or below 16 Mb in virtual storage. 


Generally, you will invoke the TSO message issuer routine via the CALLTSSR or 
LINK macro, passing the address of the input parameter list in register 1. 


The IKJEFFMT macro, which maps the input parameter list for IKJEFF02, 
allows the user to request the standard format (the default) or the extended 
format of the parameter list. The extended format must be used if the message 
inserts and/or the extract buffers being passed to IKJEFFO2 reside above 16 Mb 
in virtual storage. If they reside below 16 Mb, you do not need to use the 
extended format. However, all 31-bit addresses must be valid (zero high order 
bit). Note that the MTFMT bit must reflect the format of the parameter list you 
are using. 
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Standard Format of Input Parameter List 


Offset 
Dec Hex 
0 0 
4 4 
8 8 
12 C 
12 C 
16 10 
20 14 
21 15 
24 18 
25 19 
28 1C 
32 20 
33 21 


Field Name 
MTPLPTR 


MTCPPLP 


MTECBP 
MTRESV1 
MTHIGH 
MTCSECTP 


MTSW!1 
MTNOIDSW 
MTPUTLSW 


MTWTOSW 
MTHEXSW 


MTKEY1SW 


MTJOBISW 


MTWTPSW 


MTNHEXSW 


MTREPLYP 


MTSW2 
MT20LDSW 


MTDOMSW 


MTNOXQSW 


MTNPLMSW 
MTPGMSW 
MTEXTRCN 
MTFMT 
MTRESV2 
MTOLDPTR 


MTEXTRLN 
MTEXTRBF 
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Contents 


Address of message description section of this parameter list. (The 
message description section begins with the MTCSECTP entry.) 


Address of TMP’s CPPL control block (required for PUTLINE or 
PUTGET). 


Address of optional communications ECB for PUTLINE or PUTGET. 


Reserved. 
High-order bit of reserved field turned on for standard linkage. 


Address of an assembly module or a CSECT containing IKJTSMSG 
macros that build message identifications and associated texts. 


One byte field of switches. 
1... ..... Message is printed; no messageid is needed. 


.l.. ..... Message issued as PUTLINE. (Message inserts for a second 
level message must be listed before inserts for a first level 
message.) If this bit is zero, message issued as a PUTGET, 
with second level message required and inserts for second 
level messages necessarily following inserts for first level 
messages. 


1. ..... Message issued as a WTO. Default is PUTGET. 


..1..... Number translations to printable hexadecimal rather than 
default of printable decimal. 


1... Modeset from key 1 to key 0 before issuing a PUTLINE or 
PUTGET message. Default is no modeset. 


.1... Blanks are compressed from inserts in the format of 
JOBNAME ( JOBID ). The blanks between (1) the 
JOBNAME and opening parenthesis and (2) the JOBID and 
closing parenthesis are removed. The maximum value for 
the message and insert lengths is 252 characters. Inserts and 
messages greater than 252 characters are truncated. 


..1. Message issued as WTO with write-to-programmer routing 
code. Inserts are handled the same as for PUTLINE. 
Default is PUTGET. 


..1 Number translations to printable decimal, even if larger than 
X‘FFFF’. Default is printable hex above X‘FFFF’. 


Address of reply from PUTGET. The reply text is preceded by a 
two-byte field containing length of text plus header field. 


One byte field of switches. 


1... ..... Field MTOLDPTR points to second level message already in 
PUTLINE/PUTGET (Output Line Descriptor) format. 
Default is IKJTSMSG format. 


Delete WTP or WTO messages from the display console, 
using the delete operator message macro. 


— 
. 


1. ..... Override default of X” around inserts converted to printable 
hex. 


..1  ..... Override default of error message if PUTLINE fails. 
1... Request an error message if PUTGET fails. 
.1.. Request an extract and a message. 
..0. Request standard (24-bit) format of this parameter list. 
Reserved. 


Pointer to OLD for second level message, required if MTZ2OLDSW bit 
is ON. 


Length of extract buffer. 


Pointer to extract buffer supplied by caller. 


Dec Hex § Field Name 
36 24 MTEXTRL2 
37 25 MTEXTRB2 
40 28 MTMSGID 
44 2C MTINSRTS 
44 2C MTLEN 

44 2C MTHIGHL 
44 2C MTINSRT 
45 2D MTADDR 


Extended Format of Input Parameter List 


Offset 

Dec Hex Field Name 

0 0 MTPLPTR 

4 4 MTCPPLP 

8 8 MTECBP 

12 C MTRESV1 

12 C MTHIGH 

16 10 MTCSECTP 

20 14 MTSWI1 
MTNOIDSW 
MTPUTLSW 
MTWTOSW 
MTHEXSW 
MTKEYISW . 
MTJOBISW 
MTWTPSW 
MTNHEXSW 

21 15 MTEXTRLN 

22 16 MTEXTRL2 

23 17 MTRESV3 


Contents 
Length of extract buffer for second level message. 
Pointer to extract buffer supplied by caller for second level message. 


Message’s identifier in message CSECT, padded with blanks on the 
right. 

Insert information for message. The following two fields are supplied 
for each insert. 

Length of an insert for the message. 


High-order bit is on if necessary to translate the first 1-4 bytes of the 
insert from hexadecimal to character (printable hexadecimal or decimal 
depending on whether MTHEXSW is set to ON or OFF). 


Refers to an insert entry. 


Address of an insert for the message. 


Contents 


Address of message description section of this parameter list. (The 
message description section begins with the MTCSECTP entry.) 


Address of TMP’s CPPL control block (required for PUTLINE or 
PUTGET). 

Address of optional communications ECB for PUTLINE or PUTGET. 
Reserved. 

High-order bit of reserved field turned on for standard linkage. 


Address of an assembly module or a CSECT containing IKJTSMSG 
macros that build message identifications and associated texts. 


One byte field of switches. 
1... .... Message is printed; no messageid is needed. 


.l.. ..... Message issued as PUTLINE. (Message inserts for a second 
level message must be listed before inserts for a first level 
message.) If this bit is zero, message issued as a PUTGET, 
with second level message required and inserts for second 
level messages necessarily following inserts for first level 
messages. 


1. .... Message issued asa WTO. Default is PUTGET. 


..1..... Number translations to printable hexadecimal rather than 
default of printable decimal. 


1... Modeset from key 1 to key 0 before issuing a PUTLINE or 
PUTGET message. Default is no modeset. 


.1... Blanks are compressed from xx(yy) format inserts. Default 
is nO compression. 


..1. Message issued as WTO with write-to-programmer routing 
code. Inserts are handled the same as for PUTLINE. 
Default is PUTGET. 


..1 Number translations to printable decimal, even if larger than 
X‘FFFF’. Default is printable hex above X‘'FFFF’. 


Length of extract buffer. 
Length of second extract buffer. 


Reserved. 
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Dec Hex Field Name Contents ’ 
24 18 MTSW2 One byte field of switches. J 
MT20OLDSW 1... ..... Field MTOLDPTR points to second level message already in 
PUTLINE/PUTGET (Output Line Descriptor) format. 
Default is IKJTSMSG format. 
MTDOMSW __.|1.._..... Delete WTP or WTO messages from the display console, 
using the delete operator message macro. 
MTNOXQSW_ |. ..... Override default of X” around inserts converted to printable 
hex. 
MTNPLMSVW _....1_ ..... Override default of error message if PUTLINE fails. 
MTPGMSW 1... Request an error message if PUTGET fails. 
MTEXTRCN .1.. Request an extract and a message. 
MTFMT ..1. Request extended (31-bit) format of this parameter list. 
25 19 MTRESV2 Reserved. 
28 1C MTOLDPTR Pointer to OLD for second level message, required if MTZ2OLDSW bit 
is on. 
32 20 MTEXTRBF Pointer to extract buffer supplied by caller. 
36 24 MTEXTRB2 __—s~Pointer to extract buffer supplied by caller for second level message. 
40 28 MTMSGID Message’s identifier in message CSECT, padded with blanks on the 
right. 
44 2€ MTREPLYP _ Address of reply from PUTGET. 
48 30 MTINSRTS Insert information for message The following two fields are supplied 
for each insert. 
48 30 MTLEN Length of an insert for the message. 
48 30 MTHIGHL High-order bit is on if necessary to translate the first 1-4 bytes of the 
insert from hexadecimal to character (printable hexadecimal or decimal . 
depending on whether MTHEXSW is set to ON or OFF). : 
48 30 MTINSRT Refers to an insert entry. 
52 34 MTADDR Address of an insert for the message. 


The return code from the TSO message issuer routine is contained in register 15 


as follows: 

0 - Message issued successfully. 

76 - Error in parameter list. A diagnostic message is also issued. 
Other - PUTLINE or PUTGET return code. 


The IKJEFFMT macro maps the input parameter list. Specify the 
MTDSECT = YES option to obtain DSECT MTDSECTD instead of storage. 
Specify MTFORMAT =NEW on the IKJEFFMT macro to request the extended 
format. Specify MTFORMAT=OLD to request the standard format. 
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IKJTSMSG -- Describes Text and Insert Locations 


The IKJTSMSG macro is used to generate assembler language DC instructions 
describing the text and locations of inserts for a message which may be issued by 
the TSO message issuer routine (IKJEFFO2). All of the messages which a 
command issues should be grouped into an assembly module consisting entirely of 
IKJTSMSG macros preceded by a CSECT card and followed by an END card. 
The last IKJTSMSG macro in the CSECT must be a dummy entry with no 
operands. 


The IKJTSMSG macro may be issued by a program loaded below or above 16 
Mb in virtual storage. 


Figure 8-1 shows the syntax of the IKJTSMSG macro instruction; each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


[symbol] IKJTSMSG ('msgid msgtext'),id1l[,id2] 


Figure 8-1. The IKJTSMSG Macro Instruction 


msgid 
The identifier which will be displayed when the message is issued. 


msgtext 
The text of the message. If an insert is necessary within the text of a 
message or at the end of a message, use the following rules: 


@ The location of an insert in the middle of a message should be indicated 
by a‘,,’. 


e If the insert is to be located at the end of a message, indicate it by a ’, 
following the message text. 


idl 
The internal identifier of the message. It may be from one to four 
characters and should not contain a blank, comma, parentheses, or an 
apostrophe. This id is passed to IKJEFFO2 in the MTMSGID field of the 
parameter list. 

id2 


The internal identifier of a message to be chained to this message. For a 
PUTGET message, the first level message would have an id2 field 
identifying the second level, and the second level message could have an id2 
field to identify another second level, etc. For a PUTLINE, WTO, or 
write-to-programmer message, the second level message would have an id2 
field identifying the first level. 
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For an example of the coding involved for a CSECT containing the IKJTSMSG 
macro, see Figure 8-2. The example shows how a message module can be created ) 
for a SUBMIT command, using the IKJTSMSG macro. 


@ Message IKJ56250I is a single level PUTLINE message with one insert. 
@ Message IKJ56251I is a PUTLINE message with two levels. 
@ Message IKJ56252A is a PUTGET message with two levels. 


@ Message IKJ56253I isa PUTLINE message with an insert at the end of the 
text. 


e The IKJTSMSG macro with no operands is required to indicate the end of 
the message CSECT. 
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Figure 8-2. An Example of an IKJTSMSG Macro Instruction 
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| Chapter 9. Handling Attention Interruptions -- The STAX Service 
| Routine 


The STAX service routine creates the control blocks and queues necessary for the 
system to recognize and schedule user exits due to attention interruptions. Your 
terminal monitor program, your command processors, or the problem program 
provide the address of an attention exit to the STAX service routine by issuing the 
STAX macro instruction. You should provide attention exit routines within the 
terminal monitor program and any command processors that accept 
subcommands. Simple command or subcommand procedures should not issue a 
STAX macro instruction unless the STAX routine specified by the TMP or the 
calling command processor cannot process an attention interruption adequately. 


The STAX service routine may be invoked in either 24- or 31-bit addressing 
mode. The attention exit routine receives control in the same addressing mode in 
which the respective STAX macro 1s issued. 


With the exception of the TPUT ASID buffers for TCAM, when the user enters 
an attention interruption from the terminal, the TGET, TPUT, and TPG buffers 
are flushed. Any data contained in these buffers is lost. If the user then attempts 
to continue processing from the point of interruption, he may have lost an input 
or an output record, or an output message from the system. 


Attention processing gives the user the ability to specify exit routines that receive 
control asynchronously when the attention key is struck or when an interruption 
occurs as a result of the simulated attention facility (STATTN macro). The 
mechanism used to request attention exits is the STAX macro. When the STAX 
macro is issued, a TAXE (terminal attention exit element) is created and placed 
on a queue. The TAXE queue is ordered according to the attention level, and the 
attention level determines the order in which the attention exits are given control. 
If the ATTENTION key is struck once, the first level attention exit is given 
control. If the key is struck twice, the second level attention exit is given control. 
When placing a TAXE on the TAXE queue, two rules apply: 


1. An attention exit routine for a task will always occupy a higher attention level 
than the attention exit of any of its subtasks. 


2. The attention exit routine is placed at the lowest possible attention level, 
without violating the first rule. 


In other words, the placement of an attention level is determined by the position 
of the task in the subtask queue relative to the position of the other tasks creating 
attention exits. The lower the subtask the lower the attention level assigned. The 
subtask queue is considered to be the mother-daughter queue only. If for any 
reason a complex task structure is created that would have a mother task with 
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multiple daughter tasks, then the order in which the daughters issue STAX 
macros must be synchronized in order to ensure predictability from day to day. 
Note that the order in which the daughters issue STAX macros, not the order in 
which the daughters are attached, determines the order in which the associated 
TAXEs are placed on the TAXE queue. 


If a task has issued multiple STAX macros, the order in which the associated 
TAXE is placed on the TAXE queue is determined by the second rule. 


Attention levels can change during execution of the session for three reasons: 


1. A task has issued STAX and its daughter then issues STAX. In this case the 
attention exit for the first task would have an attention level of one until its 
subtask had issued STAX. The daughter task would then have an attention 
level of one and the original task would have a level of two. 


2. A task that has established an attention exit environment abnormally 
terminates or exits. When this occurs the TAXEs for that task are freed. The 
remaining TAXEs then assume the new attention level relative to its position 
on the TAXE queue. 


3. The STAX macro is used to cancel the last attention exit established by a 
task. 


When generating an attention interruption by striking the ATTENTION key, the 
ATTENTION level is recorded by counting the number of times the 
ATTENTION key has been struck. If the number of times the key 1s struck 
exceeds the number of available attention levels, an “!I”” message is sent to the 
terminal. If the attention has been accepted, an “!” message is sent to the 
terminal to indicate that the attention exit is being scheduled. If an attention 
interruption is received while a previously requested (lower attention level) 
attention exit is in the process of being scheduled, the first attention exit is 
canceled and the new attention exit is scheduled. This will be true until control 
has been passed to the user’s attention exit. 


Prior to passing control to the attention exit, the task under which the attention 
exit is running will have all its subtasks stopped. Note, however, that if a system 
routine (SVRB on RB chain) is executing for one of the TCBs and has not 
specified STAX DEFER = NO (see below for expanded explanation), then the 
scheduling of the attention exit will be deferred until the completion of such 
system routines. All SVRBs start execution in a STAX DEFER = YES state and 
all other RBs start execution in a STAX DEFER=N0O state. Consequently, the 
presence of an SVRB on a TCB’s RB chain normally means attention exits will be 
deferred. When the user’s attention exit completes processing the subtasks are 
automatically restarted. If, for any reason, the attention routine requires one of 
the subtasks to be restarted, it is the responsibility of the attention exit to restart 
the task through the use of the status start facility. If the subtasks should not be 
restarted, it is the responsibility of the attention exit to use the status stop facility 
to ensure that the subtasks will not become dispatchable when the attention exit 
completes processing. See Supervisor Services and Macro Instructions for 
additional information. 
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The attention level at which the attention exit is running and all of the lower 
attention levels are considered unavailable as soon as scheduling of the exit takes 
place. Therefore, once the attention scheduling has begun, only higher attention 
levels are available for use until the attention exit completes processing. 


You can use the STAX macro not only to specify and cancel attention exits, but 
also to defer the dispatching of attention exits. The DEFER operand of STAX 
can be specified to set an indicator that will postpone the dispatching of attention 
exits for a TCB and all of the TCBs above it on the mother-daughter TCB chain. 
When STAX with the DEFER=YES option is specified, a bit in the RB that 
represents the issuer’s routine is set (or reset). The indicator in the TCB, which 
allows or defers the dispatching of attention exits, is set equal to the result of 
ORing all of these bits in the RBs on the TCB RB chain. When the TCB defer 
indicator is off for a TCB and all of its subtasks, then attention exits will be 
dispatched. If the defer indicator is on for a TCB or any of its subtasks, then 
attention exits will be deferred until the defer indicator(s) for the TCB and all of 
its subtasks are off. When an attention exit can once again be dispatched, the 
DEFER=NO operand can be used to enable it to be dispatched. 


The deferral bit setting of a routine (RB) can be changed or propagated to other 
routines (RBs) which are used by the original RB. There are three cases to be 
considered. 


1. A new RB is created and placed on the RB queue along with the original RB. 
This can occur if the original RB issues a LINK. In this situation, the routine 
that has been linked maintains its own deferral bit setting. The deferral bit 
setting of the original RB is not passed to the new RB, nor is the defetral bit 
setting of the new RB passed back to the original RB. 


2. A new RB is created and placed on the RB queue and the original RB is 
destroyed. This can occur if the original RB issues an XCTL macro. The 
routine receiving control under the new RB receives the deferral bit setting of 
the original RB. 


3. No new RB is created but control is passed to a routine running under the 
original RB. This can occur if the original RB issues a CALL or LOAD 
macro. The called or loaded routine runs under the original RB. If the called 
or loaded routine issues a STAX macro instruction with the DEFER option, 
then the deferral bit setting is changed for the original RB. 


Note: Tasks within a tree structure being stopped for the attention exit 
scheduling will be stopped in an indeterminate order when any are deferring 
attention exits. As a result, care must be taken to control intertask dependencies 
and dependencies on scheduling attention exits. Failure to do so may result in an 
intertask deadlock that can only be relieved by canceling the TSO user. 
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Specifying a Terminal Attention Exit -- the STAX Macro Instruction 2 


Use the STAX macro instruction to specify the address of an attention exit 
routine that is to be given control asynchronously when a user strikes the 
attention key or when a simulated attention is specified. (See the STATTN macro 
instruction for a description of the simulated attention function.) 


The STAX macro instruction can also be used to cancel the last attention exit 
routine established by the task. To do this, specify the STAX macro instruction 
without any operands. 


The STAX macro instruction is used only in a time sharing environment. When a 
task other than a TSO user issues the STAX macro, no action is taken. In 
addition, attention exits can be established only for time sharing tasks operating 
in the foreground. 


The system routines that process attention handling require that the STAX 
parameter list remain unchanged for the life of the program. Because the 
expansion of the STAX parameter list is usually located in an area that is reusable 
by the active program, you should either code the necessary protection to prevent 
overlays or you should make a copy of the parameter list in an area that is 
non-reusable. 


Issue the STAX macro instruction to provide the information required by the 

STAX service routine. The STAX macro may be issued in 24- or 31-bit 

addressing mode. An attention exit routine receives control in the same ’ 
addressing mode in which the STAX macro is issued. J 


The STAX macro instruction has a list, an execute, and a standard form. 


The list form of the STAX macro instruction (MF=L) generates a STAX 
parameter list. The execute form of the STAX macro instruction 

(MF = E,address) completes or modifies that list and passes its address to the 
STAX service routine. The standard form does not require you to specify MF=L 
or MF=E. 


Figure 9-1 shows the format of the list and execute forms of the STAX macro 
instruction; each of the operands is explained following the figure. Appendix A 
describes the notation used to define macro instructions. 


[symbol] STAX exit address [,OBUF=(output buffer address,size) ] 
[, IBUF=(input buffer address,size) ] 
[ ,USADDR=user address] 


, REPLACE=] YES 
NO 


| ag | 


»MF=L 
»,MF=(E,address) 


b | 
Figure 9-1. The STAX Macro Instruction -- List and Execute Forms J 
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Note: When the STAX macro ts issued in 31-bit addressing mode, exit addr and 
USADDR may reside above 16 Mb in virtual storage. All other input must reside 
below 16 Mb. 


exit address 
Specify the entry point of the routine to be given control when an attention 
interruption is received. You must specify the exit address in both the list 
and the execute forms of the STAX macro instruction when you are 
establishing an attention interruption handling exit. 


You need not specify an exit address if you are using the DEFER operand 
as long as you code no other operands (except the MF operand). If you 
exclude the exit address and code no other operands, the STAX service 
routine cancels the previous attention exit established by the task issuing this 
STAX macro instruction. 


OBUF = (output buffer address,output buffer size) 
Output buffer address - Supply the address of a buffer you have obtained 
and initiated with the message to be put out to the terminal user who 
entered the attention interruption. This message may identify the exit 
routine and request information from the terminal user. It is sent to the 
terminal before the attention exit routine is given control. 


Output buffer size - Indicate the number of characters in the output buffer. 
The size may range from 0 to 32,767 (2!°-1) inclusive. 


IBUF = (input buffer address,input buffer size) 
Input buffer address - Supply the address of a buffer you have obtained to 
receive responses from the terminal user. The attention exit routine is not 
given control until the STAX service routine has placed the terminal user’s 
reply into this buffer. 


Input buffer size - Indicate the number of bytes you have provided as an 
input buffer. The size may range from 0 to 32,767 (2'°-1) inclusive. 


USADDR = (user address) 
The user address is a 24- or 31-bit address that points to any information 
you want passed to your attention handling exit routine when it is given 
control. When the attention exit gains control, register 1 points to three 
words of storage, one of which contains the user address. 


REPLACE = YES or NO 
YES indicates that the attention exit specified by this STAX macro 
instruction replaces any attention exit specified by a STAX macro 
instruction previously issued by this task. YES is the default value. 
REPLACE implies establishing a new attention exit routine for the task, if 
no previous attention exit has been established. 


NO indicates that this attention exit be established as a new attention exit 


for this task, in addition to any that have been previously established for 
this task. 


Chapter 9. Handling Attention Interruptions -- The STAX Service Routine 9-5 


DEFER = YES or NO 
The DEFER operand is optional. If the DEFER operand is coded in the 
STAX macro instruction, the option you request (YES or NO) applies to all 
tasks within the task chain in which the macro instruction was issued. Any 
task may issue the STAX macro instruction to specify DEFER = YES or 
NO; the issuing task need not itself have provided an attention exit routine. 
If the DEFER operand 1s not coded in the macro instruction, no action is 
taken by the STAX service routine regarding the deferral of attention exits. 


YES indicates that any attention interruptions received are to be queued 
and are not to be processed until another STAX macro instruction is 
executed specifying DEFER=NO, or until the program that issued the 
STAX with the DEFER = YES terminates. 


NO indicates that the defer option is being canceled. Any attention 
interruptions received while the defer option was in effect will be processed. 
If the DEFER operand is omitted, the control program leaves the deferral 
status unchanged. 


Be aware that if a program issues a STAX macro instruction specifying 
DEFER = YES, the program can get into a situation where an attention 
interruption cannot be received from the terminal. If your program enters a 
loop or an unending wait before it has issued a STAX macro instruction 
specifying DEFER =NO, you cannot regain control at the terminal by 
entering an attention interruption. 


You need not specify an exit address in a STAX macro instruction issued 
only to change deferral status. 


MF=L 
This specifies the list form of the STAX macro instruction. It generates a 
STAX parameter list. 


MF =(E, address) 
This specifies the execute form of the STAX macro instruction. It 
completes or modifies the STAX parameter list and passes the address of 
the parameter list to the STAX service routine. Place the address of the 
STAX parameter list (the address of the list form of the STAX macro 
instruction) into a register and specify that register number within 
parentheses. 


You can place each of the required address and size parameters into registers and 
specify those registers, within parentheses, in the STAX macro instruction. 
Figure 9-2 shows how an execute form of the STAX macro instruction may look 
if you load all the required parameters into registers. 


(2) ,IBUF=((3),(4)) ,OBUF=((5),(6)),USADDR=(7) ,MF=(E,(1)) 


Figure 9-2. Using Registers in the STAX Macro Instruction 
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J 


The STAX Parameter List 


When the list form of the STAX macro instruction expands, it builds the STAX 
parameter list. The list form of the macro instruction initializes this STAX 
parameter list according to the operands you have coded. The execute form of 
the STAX macro instruction modifies the STAX parameter list and passes its 
address to the STAX service routine. 


Figure 9-3 describes the contents of the STAX parameter list for MVS/370 and 
MVS/XA. Figure 9-4 describes the contents of the STAX parameter list 
extension for MVS/XA. 


a 


STXEXIT Contains the address of the attention exit routine to receive control in 
response to an attention interruption. This is the address you supplied 
as the exit address operand on the STAX macro instruction. 


STXISIZ Contains a binary number representing the size of the input buffer you 
provided as the IBUF operand on the STAX macro instruction. The 
maximum buffer size is 32,767 bytes. 


STXOSIZ Contains a binary number representing the size of the output buffer 
you provided as the OBUF operand on the STAX macro instruction. 
The maximum buffer size is 32,767 bytes. 


STXOBUF Contains the address of the output buffer you provided as the OBUF 
operand on the STAX macro instruction. 


STXIBUF Contains the address of the input buffer you provided as the IBUF 
operand on the STAX macro instruction. 


STXOPTS STAX option flags. 
REPLACE= YES 
REPLACE = NO 
Defer attention interruption processing, that is DEFER= YES. 


Cancel the deferral of attention interruption processing, that is 
DEFER=NO. 


| Indicates that the CLIST attention counter should be increased by 1. 
Indicates that the CLIST attention counter should be decreased by |. 


In. MVS/XA, indicates that STXFNUM contains a format number. In 
MVS/370, this bit is zero. 


Reserved bits. 
STXUSER Address of user’s parameter list for MVS/370 format 


Figure 9-3. The STAX Parameter List 


STAX format flags. 


Contains a format number indicating that the MVS/XA version of the 
STAX parameter list is used. (MVS/XA only) 


Reserved bytes. (MVS/XA only) 


STXNUSER Contains the address of the parameters you want passed to your 
attention handling exit routine when it is given control. This is the 
address you supplied as the USADDR operand on the STAX macro 
instruction. (MVS/XA only) 


Figure 9-4. The STAX Parame‘er List Extension for MVS/XA 
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Coding Example of the STAX Macro Instruction 


The coding example shown in Figure 9-5 uses the list and the execute forms of 
the STAX macro instruction to set up an attention handling exit. The OBUF 
operand provides a message to be written to the terminal when the attention 


interruption 1s received, and the IBUF operand provides space for an input buffer. 


This example does not code the REPLACE operand in the macro instruction; 
YES 1s the default value. The attention handling exit established by this 
execution of the STAX macro instruction replaces the previous attention handling 
exit established for this task. 
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Return Codes from the STAX Service Routine 


Control is returned to the instruction following the STAX macro instruction. J 
When control is returned, register 1 will contain the address of the user parameter 

list provided for the previous exit for this task or will contain zero. The register 

will contain zero if this is the first STAX issued for this task, a STAX with a 

cancel option, or a STAX with only the DEFER option. If an error was detected 

(return code 8), then the contents of register 1 will be the same as it was at entry. 

Register 15 will contain one of the following return codes: 


Code Meaning 
0 The STAX service routine successfully completed the function you requested. 


4 Deferral of attention exits has already been requested and is presently in effect. Any other 
operands you specified in the STAX macro instruction have been processed successfully. 


8 Invalid user of DEFER option (asynchronous exit routine). 


If any combination of parameters or the parameters themselves are invalid, an 
ABEND will be issued. 


The types of errors that will cause an ABEND are: 
e Both DEFER= YES and DEFER =NO are specified. 
e Invalid input buffer address (storage not in same key as user’s TCB). 


e Invalid buffer size (input or output). } 
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Chapter 10. Dynamic Allocation of Data Sets - The Dynamic 
Allocation Interface Routine (DAIR) 


Considerations 


Dynamic allocation routines allocate, free, concatenate, and deconcatenate data 
sets dynamically; that is, during problem program execution. With TSO, dynamic 
allocation permits the terminal monitor program, command processors, and other 
problem programs executing in the foreground region to allocate data sets after 
LOGON and free them before LOGOFF. 


For a complete discussion of dynamic allocation, see SPL: System Macros and 
Facilities. 


The dynamic allocation routines may be accessed by TSO directly or through the 
dynamic allocation interface routine (DAIR). Though its use is not recommended 
because of reduced functions and additional system overhead, DAIR can be used 
to obtain information about a data set and, if necessary, invoke dynamic 
allocation routines to perform the requested function. 


You can use DAIR to perform the following functions: 


Obtain the current status of a data set 

Allocate a data set 

Free a data set 

Concatenate data sets 

Deconcatenate data sets 

Build a list of attributes (DCB parameters) to be assigned to data sets 
Delete a list of attributes 


The user must correctly initialize the DAIR parameter block (DAPB) before 
calling DAIR. Unused fields should be zeroed or blanked (if character items). 


Specifying the data set name and the member name for DAIR entry code X‘08’ 
causes the data set to be allocated but no check is done to see if the member 
exists. To verify that the member really exists: 

e Allocate the data set with the member name using DAIR entry code X‘08’. 
@ Open the data set with DSORG=PO, MACRF=R. 


e Issue BLDL for the member. (The BLDL return code will indicate whether 
the member is there or not.) 
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Using DAIR 


@e Close the data set. 


e If BLDL indicates that the member does not exist, unallocate the data set 
using ddname and DAIR entry code X‘18’. 


Invoke the DAIR service routine via a CALLTSSR macro instruction, specifying 
the entry point IKJDAIR in load module IKJDAIR. 


The DAIR service routine may be invoked in either 24- or 31-bit addressing 
mode. When invoked in 31-bit addressing mode, DAIR may be passed input 
above 16 Mb in virtual storage. 


The control block structure required by the DAIR service routine is shown in 
Figure 10-1. Note that the DAIR parameter block (DAPB) is a variable-size 
block; the block size depends upon the function requested by the calling routine. 
That function is indicated to the DAIR service routine by the code in the first two 
bytes of the DAIR parameter block. (See “Processing Terminal Requests -- The 
TSO Service Routines” for a description of the CALLTSSR macro and a list of 
IBM-supplied mapping macros for parameter lists.) 
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J 


CALLTSSR 


Figure 10-1. Control Blocks Passed to DAIR 


Chapter 10. Dynamic Allocation of Data Sets - The Dynamic Allocation Interface Routine (DAIR) 10-3 


The DAIR Parameter List (DAPL) 


At entry to DAIR, register 1 must point to a DAIR parameter list that you have J 
built. Figure 10-2 shows the format of the DAPL. The addresses of the user 

profile table, environment control table, and protected step control block may be 

obtained from the command processor parameter list (CPPL) that the TMP 

passes to your command processor. Additional information on the address and 

creation of the user profile table, environment control table, and protected step 

control block is shown in Figure 7-2 (the command processor parameter list). 


frit | conenmorMennng 


DAPLUPT The address of the user profile table. 
DAPLECT The address of the environment control table. 
DAPLECB The address of the calling program’s event control block. The ECB is 


one word of real storage declared and initialized to zero by the calling 
routine. 


DAPLPSCB The address of the protected step control block. 


DAPLDAPB | The address of the DAIR parameter block, created by the calling 
routine. 


Figure 10-2. Format of the DAIR Parameter List (DAPL) 
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The DAIR Parameter Block (DAPB) 


( The fifth word of the DAIR parameter list must contain a pointer to a DAIR 
parameter block built by the calling routine. 


It is a variable-size parameter block that contains, in the first two bytes, an entry 
code that defines the operation requested by the calling routine. The remaining 
bytes contain other information required by DAIR to perform the requested 
function. Figure 10-3 1s a list of the DAIR entry codes and the functions 
requested by those codes. 


Function Performed by DAIR 
Test if a given DSNAME or DDNAME is currently allocated to the caller. 


Test if a given DSNAME is currently allocated to the caller, or is in system catalog. 


Allocate a data set by DSNAME. 
Concatenate data sets by DDNAME. 
Deconcatenate data sets by DDNAME. 


Search the system catalog for all qualifiers fora DSNAME. (The DSNAME alone 
represents an unqualified index entry.) 


Free a data set. 

Allocate a DDNAME to a terminal. 

Allocate a data set by DDNAME or DSNAME. 
Perform a list of operations. 

Mark data sets as not in use. 

Allocate a SYSOUT data set. 


Associate DCB parameter with a specified name for use with subsequent allocations. 


Figure 10-3. DAIR Entry Codes and Their Functions 


The DAIR parameter blocks have the formats shown in the following tables. The 
formats of the blocks depend upon the function requested by the calling routine. 
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Code X‘00’ - 


DA00CD 
DAO00FLG 


Byte 1 
0000 .... 


Byte 2 
0000 0000 


DAO00PDSN 


DA00DDN 
DAO0OCTL 


00.0 0000 
gas nes 


DAO00DSO 
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Determine if DDNAME or DSNAME Allocated 


Build the DAIR parameter block shown in Figure 10-4 to request that DAIR 
determine whether or not the specified DSNAME or DDNAME is allocated. 


Number 
of = Contents or Meaning 


Entry code X‘0000° 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 


Reserved. Set to zero. 

DSNAME or DDNAME is permanently allocated. 
DDNAME is a DYNAM. 

The DSNAME is currently allocated. 

The DDNAME is currently allocated to the terminal. 


Reserved. Set to zero. 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46 byte field with the following format: 


The first two bytes contain the length, in bytes of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified, and padded to the 
right with blanks. 


Contains the DDNAME for the requested data set. If a DSNAME is 
present, the DAIR service routine ignores the contents of this field. 


A flag field: 


Reserved bits. Set to zero. 
Prefix userid to DSNAME. 


Reserved bytes; set these bytes to zero. 


A flag field. These flags describe the organization of the data. They are 
returned to the calling routine by the DAIR service routine. 


Indexed sequential organization 

Physical sequential organization 

Direct organization 

BTAM or QTAM line group 

QTAM direct access message queue 
QTAM problem program message queue 
Partitioned organization 

Unmovable 


Figure 10-4. DAIR Parameter Block -- Entry Code X‘00’ 


After DAIR searches the data set entry for the fully qualified data set name, 
register 15 contains one of the following DAIR return codes: 


See “Return Codes from DAIR” for return code meanings. 


J 


Code X‘04’ - Determine if DSNAME Allocated or in System Catalog 


Build the DAIR parameter block shown in Figure 10-5 to request that DAIR 
determine whether or not the specified DSNAME is allocated. DAIR also 
searches the system catalog to find an entry for the DSNAME. 


Number 
of Bytes Contents or Meaning 


DA04CD 
DA04FLG 


Byte | 
0000 0..0 
me 
1. 


Byte 2 
0000 0000 


DA04CTRC 


DA04PDSN 


DAO4CTL 


00.0 0000 
salle. Be 


DA04DSO 


Entry code X‘0004’ 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 


Reserved bits. Set to zero. 
DAIR found the DSNAME in the catalog. 
The DSNAME is currently allocated. 


Reserved. Set to zero. 
Reserved. Set to zero. 


These two bytes will contain an error code from the catalog 
management routines if an error was encountered by catalog 
management. 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46-byte field with the following format: 


The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified, and padded to the 
right with blanks. 


A flag field: 


Reserved bits. Set to zero. 
Prefix userid to DSNAME. 


Reserved bytes; set these bytes to zero. 


A flag field. These flags are set by the DAIR service routine; they 


describe the organization of the data set to the calling routine. These 
flags are returned only if the data set is currently allocated. 


Indexed sequential organization 

Physical sequential organization 

Direct organization 

BTAM or QTAM line group 

QTAM direct access message queue 
QTAM problem program message queue 
Partitioned organization 

Unmovable 


Figure 10-5. DAIR Parameter Block -- Entry Code X‘04’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 8, 52 


See “Return Codes from DAIR” later in this section for return code meanings. 
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Code X‘08’ - Allocate a Data Set by DSNAME 


Build the DAIR parameter block shown in Figure 10-6 to request that DAIR ) 
allocate a data set. The exact action taken by DAIR depends upon the presence 
of the optional fields and the setting of bits in the control byte. 


If the data set is new and you specify DSNAME, (NEW, CATLG) the data set is 
cataloged upon successful allocation. This is the only time a data set will be 
cataloged at allocation time. If the catalog attempt is unsuccessful, the data set is 
freed. If the proper indices are not present, the indices are built. 


To allocate a utility data set use DAIR code X‘08’ and use a DSNAME of the 
form &name. If the &name is found allocated, that data set is used. If the 
&name is not found, a new data set is allocated. 


To supply DCB information, provide the name of an attribute list that has been 
defined previously by a X‘34’ entry into DAIR. 


When setting disposition in a parameter list, only one bit should be on. 


The DAIR parameter block required for entry code X‘08’ has the format shown 
in Figure 10-6. 


ae. Contents or Meaning 


DAO08&CD Entry code X‘0008’ 


DA08FLG A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 


Byte 1 


ree The data set is allocated but a secondary error occurred. Register 15 
contains an error code. 


-000 0000 Reserved bits. Set to zero. 
Byte 2 Reserved. Set to zero. 


DA08DARC This field contains the error code, if any, returned from the dynamic 
allocation routines. (See “Return Codes from Dynamic Allocation.”) 


DA08CTRC This field contains the error code, if any, returned from catalog 
management routines. (See “Return Codes from DAIR.”) 


DA08PDSN Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46 byte field with the following format: 


The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. If this field (DAO8PDSN) is zero, the system 
generates a data set name unless bit 5 in DAO8CTL is on, in which case 
a DUMMY data set is allocated. The system also generates a name if 
the DAO8PDSN field points to a DSNAME buffer which has a length 
of 44, is initialized to blanks, and bit 5 in DAO8CTL is off. 


DA08DDN This field contains the DDNAME for the data set. If a specific 
DDNAME is not required, fill this field with eight blanks; DAIR will 
place in this field the DDNAME to which the data set is allocated. 


Figure 10-6 (Part 1 of 3). DAIR Parameter Block -- Entry Code X‘08’ 
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DAO8UNIT This is an eight-byte field containing an esoteric group name, a generic 
group name, or a specific device address (in EBCDIC). If the unit 
information is less than eight characters, it must be padded to the right 
with blanks. If no information is to be provided, the field must be 
blank. In this case, DAIR will obtain information from the protected 
step control block. If there is no unit information in the PSCB, then a 
default of all direct access devices is used. The specified unit 
information will be ignored if volume information is obtained from the 
catalog, unless the unit specification is a subset of that obtained from 
the catalog. In this case the specified unit information will override the 
returned information. 


DAO8SER Serial number desired. Only the first six bytes are significant. If the 
serial number is less than six bytes, it must be padded to the right with 
blanks. If the serial number is omitted, the entire field must contain 
blanks. In this case the following is done: if the data set is a new data 
set, the system determines the volume to be used for the data set based 
on the unit information. If the data set already exists, volume and unit 
information are obtained from the catalog. If the information is not 


found in the catalog, the allocation request is denied. 


DAO8BLK This is a four-byte field used as follows: if the data set is a new data 
set and bit 0 in DAO8CTL is off and bit 1 in DAO8CTL is on, this field 
is used with DAO8PQTY to determine the amount of direct access 
space to be allocated for the data set. If bit 6 of DAO8CTL is off, the 
field is also used as DCB blocksize specification. The value for 
blocksize must be placed in the low-order two bytes, and the high-order 


bytes must be zero. 


DAO8PQTY Primary space quantity desired. The high-order byte must be set to 
zero and the low-order three bytes should contain the space quantity 
required. If the quantity is omitted, the entire field must be set to zero. 
In the case of new direct access data sets, primary and secondary space 
and type of space are defaulted. Directory quantity is used if specified 


in DAO8DQTY. 


Secondary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the secondary space 
quantity required. If the quantity is omitted, the entire field must be 
set to zero. 


DAO8SQTY 


DA0&8DQTY Directory quantity required. The high-order byte must be set to zero; 
the low-order three bytes contain the number of directory blocks 


desired. If the quantity is omitted, the entire field must be set to zero. 


DA08MNM Contains a member name of a partitioned data set. If the name has 
less than eight characters, pad it to the right with blanks. If the name 


is omitted, the entire field must contain blanks. 


DA08PSWD Contains the password for the data set. If the password has less than 
eight characters, pad it to the right with blanks. If the password is 


omitted, the entire field must contain blanks. 
Flag byte. Set the following bits to indicate the status of the data set: 


Reserved. Set these bits to zero. 

SHR 

NEW 

MOD 

OLD 

If this byte is zero, OLD is assumed. NEW or MOD is required if 
DSNAME is omitted. 


DAO8DSP1 


0000 .... 


Figure 10-6 (Part 2 of 3). DAIR Parameter Block -- Entry Code X‘08’ 
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10-10 
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DAO8DPS2 Flag byte. Set the following bits to indicate the normal disposition of 
the data set: 


Reserved bits. Set them to zero. 
KEEP 

DELETE 

CATLG 

UNCATLG 


If this byte is zero, it is defaulted as follows: if DAO8DSP1 is NEW, 
DELETE is used; otherwise, KEEP is used. 


Flag byte. Set the following bits to indicate the abnormal disposition 
of the data set: 


Reserved bits. 
KEEP 
DELETE 
CATLG 
UNCATLG 


If this byte is zero, DAO8DPS2 will be used. 


Flag byte. These flags indicate to the DAIR service routine what 
operations are to be performed: 


0000 .... 


DAO8DPS3 


0000 .... Set them to zero. 


Beds Indicate the type of units desired for the space parameters, as follows: 


or Units are in average block length. 
re Units are in tracks (TRKS). 

is eae Units are in cylinders (CYLS). 
Prefix userid to DSNAME. 
RLSE is desired. 


The data set is to be permanently allocated; it is not to be freed until 
specifically requested. 


A DUMMY data set is desired. 
Attribute list name supplied. 


Reserved bit; set to zero. 


Reserved bytes; set them to zero. 


A flag field. These flags are set by the DAIR service routine; they 
describe the organization of the data set to the calling routine. 


Indexed sequential organization 

Physical sequential organization 

Direct organization 

BTAM or QTAM line group 

QTAM direct access message queue 
QTAM problem program message queue 
Partitioned organization 

Unmovable 


Attribute list name, or a DD name from which DCB attributes should 
be copied (as in a JCL DCB reference). If the name is less than 8 
characters, it should be padded to the right with blanks. 


DAO8ALN 


Figure 10-6 (Part 3 of 3). DAIR Parameter Block -- Entry Code X‘08’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 8, 12, 16, 20, 28, 32, 44, 52 


See the topic “Return Codes from DAIR” for return code meanings. 
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Code X‘0C’ - Concatenate the Specified DDNAMES 


Cc Build the DAIR parameter block shown in Figure 10-7 to request that DAIR 
concatenate data sets. The DDNAMES listed in the DAIR parameter block are 
to be concatenated in the order in which they appear. All data sets listed by 
DDNAME in the DAIR parameter block must be currently allocated. 


ed Contents or Meaning 


DAO0CCD Entry code X‘000C’ 
DAOCFLG Reserved. Set this field to zero. 


DAODCDARC This field contains the error code, if any, returned from the dynamic 
allocation routines. (See “Return Codes from Dynamic Allocation.”) 


Reserved field. Set this field to zero. 
DAOCNUMB Place in this field the number of data sets to be concatenated. 
Reserved. Set this field to zero. 


DADCDDN Place in this field the DDNAME of the first data set to be 
concatenated. This field is repeated for each DDNAME to be 
concatenated. 


Figure 10-7. DAIR Parameter Block -- Entry Code X‘0C’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15. 


0, 4, 12, 52 
( See “Return Codes from DAIR” for return code meanings. 
Code X‘10’ - Deconcatenate the Indicated DDNAME 


Build the DAIR parameter block shown in Figure 10-8 to request that DAIR 
deconcatenate a data set. The DDNAME specified within the DAIR parameter 
block has been previously concatenated and is now to be deconcatenated. 


lie Contents or Meaning 


DAI0CD Entry code X‘0010’ 
DAIOFLG Reserved. Set this field to zero. 


DAIODARC This field contains the error code, if any, returned from the dynamic 
allocation routines. (See “Return Codes from Dynamic Allocation.”) 


Reserved field. Set this field to zero. 
DAIODDN Place in this field the DDNAME of the data set to be deconcatenated. 


Figure 10-8. DAIR Parameter Block -- Entry Code X‘10’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 12, 52 


See “Return Codes from DAIR” for return code meanings. 
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Code X‘14’ - Return Qualifiers for the Specified DSNAME 


Build the DAIR parameter block shown in Figure 10-9 to request that DAIR 
return all qualifiers for the DSNAME specified. 


You must also provide the return area pointed to by the third word of the DAIR 
parameter block. If the area you provide is larger than needed for all returned 
information, the remaining bytes in the area are set to zero by DAIR. If the area 
is smaller than required, it is filled to its limit, and the return code specifies this 
condition. 


Number 
of Bytes Contents or Meaning 


DA14CD Entry code X‘0014’ 
DAI4FLG Reserved. Set this field to zero. 


DA14PDSN Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46 byte field with the following format: 


The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. DSNAME alone represents an unqualified index 
entry. 


DAI14PRET Place in this field the address of the return area in which DAIR is to 
place the qualifiers found for the DSNAME. Place the length of the 
return area in the first two bytes of the return area. Set the next two 
bytes in the return area to zero. DAIR returns each of the qualifiers it 
finds in two fullwords of storage beginning at the first word (offset 0) 
within the return area. 


DAI4CTL A flag field. 


Byte 1 
00.0 0000 Reserved bits; set them to zero. 
vale “yeas Prefix userid to DSNAME. 


Reserved bytes. Set this field to zero. 


Figure 10-9. DAIR Parameter Block -- Entry Code X‘14’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 36, 40 
See “Return Codes from DAIR” for return code meanings. 
Code X‘18’ - Free the Specified Data Set 
Build the DAIR parameter block shown in Figure 10-10 to request that DAIR 
free a data set. The data set name represented by DSNAME is to be freed. If 
no DSNAME is given, the data set associated with the DDNAME is freed. If 
both DDNAME and DSNAME are given, DAIR ignores the DDNAME. 


If the specified DSNAME is allocated several times to the user, all such 
allocations are freed. 


When setting disposition in a parameter list, only one bit should be on. 
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Number 
of Bytes Contents or Meaning 


DAI8CD Entry code X‘0018° 


DAI8FLG A flag field set by DAIR before returning to the calling routine. The 
flags have the following meanings: 

Byte | 

[en 028 The data set is freed but a secondary error occurred. Register 15 

contains zero and the error information is in DAI8DARC. 


.000 0000 Reserved bits. Set to zero. 
Byte 2 Reserved. Set to zero. 


DAI8DARC This field contains the error code, if any, returned from the dynamic 
allocation routines. (See “Return Codes from Dynamic Allocation.”) 


DAIL8CTRC This field contains the error code, if any, returned from catalog 
management routines. (See “Return Codes from DAIR.”) 


DAI8PDSN Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46-byte field with the following format: 


The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. This field is zero if the DSNAME is not specified. 


DAI8DDN Place in this field the DDNAME of the data set to be freed, or blanks. 
If DSNAME is specified, this field is ignored. 


DA18MNM Contains the member name of a partitioned data set. If the name has 
less than eight characters, pad it to the right with blanks. If the name 
is omitted, the entire field must contain blanks. 


DA18SCLS SYSOUT class. The output class may be A-Z or 0-9 in the first byte. 
The second byte in the field is ignored. If SYSOUT is not specified, 
the first byte of this field must contain zeros or blanks. 


DA18DPS2 Flag byte. Set the following bits to override the normal disposition of 
the data set: 


0000 .... Reserved bits. Set them to zero. 
sae is KEEP 

DELETE 

CATLG 

UNCATLG 


If the disposition specified at allocation is to be used, this field must 
contain zero. 


DAI18CTL Flag byte. These flags indicate to the DAIR service routine what 
operations are to be performed: 


eee Prefix userid to DSNAME (requires DAI8PDSN data be available). 
00.. 0000 Reserved bits; set them to zero. 


a ey If this bit is on, permanently allocated data sets are unallocated. If the 
bit is off, the data set will be marked “not in use,” if it is permanently 
allocated. 


Reserved bytes; set this field to hexadecimal zeros. 
Figure 10-10. DAIR Parameter Block -- Entry Code X‘18’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 12, 24, 28, 52 


See “Return Codes from DAIR” for return code meanings. 


Chapter 10. Dynamic Allocation of Data Sets - The Dynamic Allocation Interface Routine (DAIR) 10-13 


Code X‘1C’ - Allocate the Specified DDNAME to the Terminal 


Build the DAIR parameter block shown in Figure 10-11 to request that DAIR » 
allocate a DDNAME to the terminal. If the DDNAME field is left blank, DAIR 

returns the allocated DDNAME in that field. To supply DCB information, 

provide the name of an attribute list that has been defined previously by a X‘34’ 

entry into DAIR, or the DDNAME of a currently allocated data set from which 

DCB attributes can be copied (as in a JCL DCB reference). 


eo Contents or Meaning 


DAICCD Entry code X‘001C’ 
DAICFLG Reserved field; set it to zero. 


DAICDARC This field contains the error code, if any, returned from the dynamic 
allocation routines. (See “Return Codes from Dynamic Allocation.”) 


Reserved field; set it to zero. 
DAICCTL Control byte. 


i The data set is to be permanently allocated; it is not to be freed until 
specifically requested. 


ale Attribute list name supplied. 
0000 .0.0 Reserved; set to zero. 


DAICDDN Place in this field the DDNAME for the data set to be allocated to the 
terminal or blanks if the allocated DDNAME should be returned in 
this field. 


DAICALN Attribute list name that has been defined previously by a X‘34’ entry 
into DAIR, or a DDNAME of a currently allocated data set from 
which DCB attributes can be copied. This field is used only if Bit 6 of 
DAICCTL is set to one. 


Figure 10-11. DAIR Parameter Block -- Entry Code X‘1C’ ) 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 12, 16, 20, 28, 52 
See “Return Codes from DAIR” later in this section for return code meanings. 
Code X‘24’ - Allocate a Data Set by DDNAME 


Build the DAIR parameter block shown in Figure 10-12 to request that DAIR 
allocate a data set by DDNAME. 


If DAIR locates the DDNAME you specify and a DSNAME is currently 
associated with it, the associated DSNAME is allocated overriding the DSNAME 
pointed to by the third word of your DAIR parameter block. The DDNAME 
may be found associated with a DUMMY, and if so an indicator is returned but 
no allocation takes place. 


If DAIR cannot allocate by DDNAME, it will give control to code X‘08’ to 
allocate by DSNAME and will generate a new DDNAME. 


When setting disposition in a parameter list, only one bit should be on. 
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aan | Contents or Meaning 


DA24CD 
DA24FLG 


Byte 1 


.000 .000 
Byte 2 
DA24DARC 


DA24CTRC 


DA24PDSN 


DA24DDN 


DA24UNIT 


DA24SER 


DA24BLK 


DA24PQTY 


Figure 10-12 (Part 1 of 3). 
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Entry code X‘0024’ 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 


The data set is allocated but a secondary error occurred. Register 15 
contains an error code. 


DDNAME requested is allocated as DUMMY. 
Reserved bits. Set to zero. 
Reserved. Set to zero. 


This field contains the error code, if any, returned from the dynamic 
allocation routines. (See “Return Codes from Dynamic Allocation.”) 


This field contains the error code, if any, returned from catalog 
management routines. (See “Return Codes from DAIR.”) 


Place in this field the address of the DSNAME buffer. The DSNAME 
buffer is a 46-byte field with the following format: 


The first two bytes contain the length, in bytes, of the DSNAME; the 
next 44 bytes contain the DSNAME, left justified and padded to the 
right with blanks. If the specified DDNAME is used, this field 
(DA24PDSN) is ignored. 


Place here the DDNAME for the data set to be allocated. This 
DDNAME is required. If the specified DDNAME is not allocated, 
then a generated DDNAME will be used with the DSNAME and the 
generated DDNAME will be returned in this field. 


This is an eight-byte field containing an esoteric group name, a generic 
group name, or a specific device address (in EBCDIC). If the unit 
information is less than eight characters, it must be padded to the right 
with blanks. If no information is to be provided, the field must be 
blank. In this case, DAIR will obtain information from the protected 
step control block. If there is no unit information in the PSCB, then a 
default of all direct access devices is used. The specified unit 
information will be ignored if volume information is obtained from the 
catalog, unless the unit specification is a subset of that obtained from 
the catalog. In this case the specified unit information will override the 
returned information. 


Serial number desired. Only the first six bytes are significant. If the 
serial number is less than six bytes, it must be padded to the right with 
blanks. If the serial number is omitted, the entire field must contain 
blanks. In this case, the following is done: 


If the data set is a new data set, the system determines the volume to be 
used for the data set based on the unit information. If the data set 
already exisis, volume and unit information are obtained from the 
catalog. If the information is not found in the catalog, the allocation 
request is denied. 


This is a four-byte field used as follows: If the data set is a new data 
set and CONTROL bit 0 is off and bit 1 is on (see below), this field is 
used with PRIMARY SPACE QUANTITY to determine the amount 
of direct access space to be allocated for the data set. If CONTROL 
bit 6 is off, the field is also used as a DCB blocksize specification. The 
value for BLOCKSIZE must be placed in the low-order two bytes. The 
high-order byte must be zero. 


Primary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the space quantity 
required. If the quantity is omitted, the entire field must be set to zero. 
In this case for new direct access data sets primary and secondary 
space, and type of space will be defaulted. Directory quantity will be 
used if specified in DA2Z4DQTY. 


DAIR Parameter Block -- Entry Code X‘24’ 


10-15 


umber 
of Bytes Contents or Meaning 


DA24SQTY Secondary space quantity desired. The high order byte must be set to 
zero; the low order three bytes should contain the secondary space 
quantity required. If the quantity is omitted, the entire field must be 
set to zero. 


DA24DQTY | Directory quantity required. The high order byte must be set to zero; 
the low order three bytes contain the number of directory blocks 


desired. If the quantity is omitted, the entire field must be set to zero. 


DA24MNM Contains a member name of a partitioned data set. If the name has 
less than eight characters, pad it to the right with blanks. If the name 


is omitted, the entire field must contain blanks. 


DA24PSWD 


Contains the password for the data set. If the password has less than 
eight characters, pad it to the right with blanks. If the password is 
omitted, the entire field must contain blanks. 


Flag byte. Set the following bits to indicate the status of the data set: 


Reserved. Set these bits to zero. 
SHR 

NEW 

MOD 

OLD 


If this byte is zero, OLD is assumed. 


Flag byte. Set the following bits to indicate the normal disposition of 
the data set: 


Reserved bits. Set them to zero. 
KEEP 

DELETE 

CATLG 

UNCATLG 


If this byte is zero, it is defaulted as follows: if DA24DSP1 is new, 
DELETE is used; otherwise KEEP is used. 


Flag byte. Set the following bits to indicate the abnormal disposition 
of the data set: 


Reserved bits. Set them to zero. 
KEEP 

DELETE 

CATLG 

UNCATLG 


If this byte is omitted (set to zero), DA24DPS2 will be used. 


Flag byte. These flags indicate to the DAIR service routine what 
operations are to be performed: 


DA24DSP1 


ie: ies Indicate the type of units desired for the space parameters, as follows: 


be.) abe Units are in average block length. 
bs eee Units are in tracks (TRKS). 
are Units are in cylinders (CYLS). 
Prefix userid to DSNAME. 
RLSE is desired. 


The data set is to be permanently allocated; it is not be freed until 
specifically requested. 


A DUMMY data set is desired. 
Attribute list name supplied. 


Reserved bil; set to zero. 


Reserved bytes; set them to zero. 


Figure 10-12 (Part 2 of 3). DAIR Parameter Block -- Entry Code X‘24’ 
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Contents or Meaning 


A flag field. These flags are set by the DAITR service routine; they 
describe the organization of the data set to the calling routine. 


Indexed sequential organization. 

Physical sequential organization. 

Direct organization. 

BTAM or QTAM line group. 

QTAM direct access message queue. 
QTAM problem program message queue. 
Partitioned organization. 

Unmovable. 


DA24ALN Attribute list name, or a DD name from which DCB attributes should 
be copied (as in a JCL DCB reference). If the name is less than eight 
characters, it should be padded to the right with blanks. 


Figure 10-12 (Part 3 of 3). DAIR Parameter Block -- Entry Code X‘24’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 8, 12, 16, 20, 52 
See “Return Codes from DAIR” for return code meanings. 
Code X‘28’ - Perform a List of DAIR Operations 
Build the DAIR parameter block shown in Figure 10-13 to request that DAIR 
perform a list of operations. This DAIR parameter block points to other DAPBs 


which request the operations to be performed. 


All valid DAIR functions are acceptable; however, code X‘14’ or another code 
X28’ are ignored. 


DAIR processes the requested operations in the order they are requested. 


DAIJIR processing stops with the first operation that fails. 


frit | Comte Meng 


DA28CD Entry code X‘0028’ 
DA28NOP 
DA28PFOP 


Place in this field the number of operations to be performed. 


DAIR fills this field with the address of the DAIR parameter block for 
the first operation that failed. If all operations are successful, this field 
will contain zero upon return from the DAIR service routine. If this 
field contains an address, register fifteen contains a return code. 


Place in this field the address of the DAIR parameter block for the first 
operation you want performed. Repeat this field, filling it with the 
addresses of the DAPBs, for each of the operations to be performed. 


DA280PTR 


Figure 10-13. DAIR Parameter Block -- Entry Code X‘28’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 8, 12, 16, 20, 24, 28, 32, 44, 52 


For return code meanings see the topic “Return Codes from DAIR.” 
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Code X‘2C’ 


Code X‘30° 


- Mark Data Sets as Not in Use 


Build the DAIR parameter block shown in Figure 10-14 to request that DAIR 
mark data sets associated with a task control block as not in use. This allows 
data set entries to be reused. 


This is the code which the TMP should pass to DAIR prior to detaching a 
command processor. This code should also be issued by any command processor 
which attaches another command processor and detaches that command processor 
directly. 


umber 
of Bytes Contents or Meaning 


DA2CCD Entry code X‘002C’ 


DA2CFLG A flag field. Set the bits to indicate to the DAIR service routine which 
data sets you want marked ‘not in use’. 


Hex 
Setting Meaning 


0000 Mark all data sets of the indicated TCB ‘not in use’. 
0001 Mark the specified DDNAME ‘not in use’. 
0002 Mark all data sets associated with lower tasks ‘not in use’. 


Place in this field the address of the TCB for the task whose data sets 
are to be marked ‘not in use’. DA2CFLG must be set to hex 0000. 


Place in this field the DDNAME to be marked ‘not in use’. DA2CFLG 
must be set to hex 0001. 


DA2CTCB 


DA2CDDN 


Figure 10-14. DAIR Parameter Block -- Entry Code X‘2C’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 52 


For return code meanings see “Return Codes from DAIR” later in this section. 


- Allocate a SYSOUT Data Set to the Message Class 


Build the DAIR parameter block shown in Figure 10-15 to request that DAIR 
allocate a SYSOUT data set to the message class. The exact action taken by 
DAIR is dependent upon the presence of the optional fields and the setting of bits 
in the control byte. To supply DCB information, provide the name of an 
attribute list that has been defined previously by a X‘34 entry into DAIR, or the 
DDNAME of a currently allocated data set from which DCB attributes can be 
copied (as in a JCL DCB reference). 


To place a SYSOUT data set in a class other than the message class, use DAIR 
entry code X‘°30’ and when the output has been written, specify the desired class 
either by using DAIR entry code X‘18’, or execute the FREE command, after the 
program has completed processing. 


When setting disposition in a parameter list, only one bit should be on. 
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J 


Number 
of Bytes Contents or Meaning 


DA30CD 
DA30FLG 


Byte 1 


.000 0000 
Byte 2 
DA30DARC 


DA30PDSN 


DA30DDN 


DA30UNIT 


DA30SER 


DA30BLK 


DA30PQTY 


DA30SQTY 


Entry code X‘0030’ 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 


The data set is allocated but a secondary error occurred. Register 15 
contains an error code. 


Reserved bits. Set to zero. 
Reserved. Set to zero. 


This field contains the error code, if any, returned from the dynamic 
allocation routines. (See “Return Codes from Dynamic Allocation.”) 


Reserved. Set this field to zero. 


Place in this field the address of the DSNAME buffer or zeros. The 
DSNAME buffer is a 46-byte field which must appear as follows: 


The first two bytes must contain 44 (X‘2C’); the next 44 bytes contain 
blanks. 


This field contains the DDNAME for the data set. If a specific 
DDNAME is not required, fill this field with eight blanks; DAIR will 
place in this field the DDNAME to which the data set is allocated. 


This is an eight-byte field containing an esoteric group name, a generic 
group name, or a specific device address (in EBCDIC). If the unit 
information is less than eight characters, it must be padded to the right 
with blanks. If no information is to be provided, the field must be 
blank. In this case, DAIR will obtain unit information from the 
protected step control block. If there is no unit information in the 
PSCB, then a default of all direct access devices is used. The specified 
unit information will be ignored if volume information is obtained from 
the catalog, unless the unit specification is a subset of that obtained 
from the catalog. In this case the specified unit information will 
override the returned information. 


Serial number desired. Only the first six bytes are significant. If the 
serial number is less than six bytes, it must be padded to the right with 
blanks. If no volume serial number is specified, the field must be 
blank. In this case, the following is done: If the data set is a new data 
set, the system determines the volume to be used for the data set based 
on the unit information. If the data set already exists, volume and unit 
information are oblained from the catalog. If the information is not 
found in the catalog, the allocation request is denied. 


Block size requested. This figure represents the average record length 
desired. 


Primary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the space quantity 
required. If the quantity is omitted, the entire field must be set to zero. 
In this case for new direct access data sets primary and secondary 
space, and type of space will be defaulted. 


Secondary space quantity desired. The high-order byte must be set to 
zero; the low-order three bytes should contain the secondary space 
quantity required. If the quantity is omitted, the entire field must be 
set to zero. 


Figure 10-15 (Part 1 of 2). DAIR Parameter Block -- Entry Code X‘30’ 
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umber 
» Bytes Contents or Meaning 


DA30PGNM | Place in this field the member name of a special user program to handle 
SYSOUT operations. Fill this field with blanks if you do not provide a 
program name. 


DA30FORM | Form number. This form number indicates that the output should be 
printed or punched on a specific output form. It is a four character 
number. This field must be filled with blanks if this parameter is 


omitted. 


SYSOUT class. The data set will be allocated to the message class, 
regardless of the class you specify here. To place a SYSOUT data set 
in a class other than the message class, use DAIR entry code X‘30’ and 
when the output has been written, specify the desired class by using 
DAIR entry code X‘18’. 


Reserved. Set this field to zero. 


“lag byte. These flags indicate to the DAIR service routine what 
operations are to be performed. 


DA300CLS 


DA30CTL 


serciaeeh Indicate the type of units desired for the space parameters, as follows: 


ee sande Units are in average block length. 
bas Units are in tracks (TRKS). 

oy, 208k Units are in cylinders (CYLS). 
Prefix userid to DSNAME 
RLSE is desired. 


The data set is to be permanently allocated; it is not to be freed until 
specifically requested. 


A DUMMY data set is desired. 
Attribute list name specified. 


~ Reserved bit; set to zero. 


Attribute list name, or a ddname from which DCB attributes should be 
copied (as in a JCL DCB reference). If the name is less than eight 
characters, it should be padded to the right with blanks. 


DA30ALN 


Figure 10-15 (Part 2 of 2). DAIR Parameter Block -- Entry Code X‘30’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 12, 16, 20, 28, 52 

See “Return Codes from DAIR” later in this section for return code meanings. 
Code X‘34’ - Associate DCB Parameters with a Specified Name 

Build the DAIR parameter block shown in Figure 10-16 to request that DCB 
parameters to be used with subsequent allocations are associated with a specified 
name (attribute name). The following functions related to attribute names are 
available using code X‘34¢’: 
1. Associate a set of DCB parameters to be used in subsequent allocations. 
2. Search on the attribute name. 


3. Delete the attribute name. 


Note: When you request that DAIR associate DCB parameters with a specified 
name, you must also build a DAIR attribute control block (DAIRACB). 
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DA34CD 
DA34FLG 


Byte 1 
DA34FIND 
.000 0000 
Byte 2 


DA34DARC 


DA34CTRL 


DA34SRCH 


DA34CHN 
ne 


ee a 
- 0000 


DA34NAME 
D/ % ADDR 


umber 
sie | mow | crmemmrotning 


Entry code X‘0034° 


A flag field set by DAIR before returning to the calling routine. The 
flags have the following meaning: 


An attribute list name was found. 
An attribute list name was not found. 
Reserved bits. Set to zero. 


Reserved. Set to zero. 


This field contains the code returned from the dynamic allocation 
routines. (See “Return Codes from Dynamic Allocation.”) 


Flag byte. These flags indicate to DAIR what operations are to be 
performed. 


Search for the attribute list name specified in field DA34NAME. 
Build and chain an attribute list. 


Delete an attribute list name. 
Reserved bits. Set to zero. 


Reserved. Set to zero. 
This field contains the name for the list of attributes. 
This field contains the address of the DAIR attribute control block 


(DAIRACB). This field need only be specified if bit 1 of DA34CTRL 
is OD. 


Figure 10-16. DAIR Parameter Block -- Entry Code X‘34’ 


After attempting the requested function, DAIR returns one of the following codes 
in register 15: 


0, 4, 12, 52 
See “Return Codes from DAIR” later in this section for return code meanings. 
DAIRACB - DAIR Attribute Control Block 
Build the DAIRACB shown in Figure 10-17 when you request that DAIR 
construct an attribute list. Place the address of the DAIRACB into the 


DA34ADDR field of the code X‘34’ DAIR parameter block shown in 
Figure 10-16. 
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Number 
of Bytes 
8 


DAIMASK 
DAILABEL 


DAITNOUT 


DAIOUTIN 
..00 0000 


DAIEXPDT 
DAIYEAR 
DAIDAY 


DAIBUFNO 
DAIBFTEK 


DAIBUFL 
DAIEROPT 
Lex: 

ae 

...0 0000 
DAIEKYLE 


DAIRECFM 


ee als 

0.0 .0.0 
DAIBLKSI 
DAILRECL 
DAINCP 


Contents or Meaning 


Reserved. 
First 6 bytes and eighth byte are reserved. 


Seventh-byte flags. These flags indicate the INOUT/OUTIN options of 
the OPEN macro. 


Use the INOUT option. 


Use the OUTIN option. 
Reserved bits. Should be set to zero. 


Reserved. Should be set to zero. 
This field contains a data set expiration date specified in binary. 
The first byte contains the expiration year. 


The next 2 bytes contain the expiration day, left justified. For example, 
the date 99352 is specified ‘630160’B. 


Reserved. Should be set to zero. 

This field contains the number of buffers required. 
This field contains the buffer type and alignment. 
Simple buffering (S). 

Automatic record area construction (A). 

Record buffering (R). 

Exchange buffering (E). 

Doubleword boundary (D). 


Fullword boundary (F). 
Reserved bits. Should be set to zero. 


This field contains the buffer length. 
This field indicates the error options: 


Accept error record. 

Skip error record. 

Abnormal EOT. 

Reserved bits. Should be set to zero. 


This field contains the key length. 
Reserved. Should be set to zero. 
This field indicates the record format: 
Fixed (F) 

Variable (V). 

Undefined (U). 

Track overflow (T). 

Blocked (B). 

Standard blocks (S). 

ASCII printer characters (A). 


Machine control characters (M). 
Reserved bit. Should be set to zero. 


This field contains the error option codes: 


Write validity check (W). 

Chained scheduling (C). 

ASCII translate (Q). 

User totaling (T). 

Reserved bits. Should be set to zero. 


This field contains the maximum block size. 
This field contains the logical record length. 


This field contains the maximum number of READ or WRITE channel 
programs before check. 


Reserved. Should be set to zero. 


Figure 10-17. DAIR Attribute Control Block (DAIRACB) 


The fields that you do not use must be initialized to zero. 
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Return Codes from DAIR 


DAIR returns a code in general register 15 to the calling routine. In addition, 
further return code information may be found in the DAxxCTRC field if the 
return code is 8 or in the DAxxDARC field if the return code is 12. 


The DAIR return codes have the following meaning: 


Return 
Code 


(decimal) 


0 


4 


8 


12 


16 


20 


24 


28 


32 


36 


40 


44 


48 


52 


Meaning 


DAIR completed successfully. 
The parameter list passed to DAIR was invalid. 


An error occurred in a catalog management routine; the catalog management error code is 
stored in the CTRC field of the DAIR parameter block. 


An error occurred in dynamic allocation; the dynamic allocation error code is stored in the 
DARC field of the DAIR parameter block. 


No TIOT entries were available for use. 
The ddname requested is unavailable. 
The dsname requested is a member of a concatenated group. 


The ddname or dsname specified is not currently allocated, or the attribute list name 
specified was not found. 


The requested data set was previously permanently allocated, or was allocated with a 
disposition of new, and was not deleted. DISP=NEW cannot now be specified. 


An error occurred in a catalog information routine (IKJEHCIR). 


The return area you provided for qualifiers was exhausted and more index blocks exist. If 
you require more qualifiers, provide a larger return area. 


The previous allocation specified a disposition of DELETE for this non-permanently 
allocated data set. Request specified OLD, MOD, or SHR with no volume serial number. 


Reserved. 


Request denied by installation exit. 


The return codes from catalog management, which are found in the DAxxCTRC 
field if the register 15 return code is 8, are documented in SPL: Data 
Management. 


Chapter 10. Dynamic Allocation of Data Sets - The Dynamic Allocation Interface Routine (DAIR) 10-23 


Return Codes from Dynamic Allocation 


The codes returned in the DAxxDARC field of the DAIR parameter block, when J 
a DAIR return code of 12 is returned, are the dynamic allocation error reason 

codes. (See SPL: System Macros and Facilities.) In addition to those return 

codes, which are converted from dynamic allocation codes back to the same codes 

which were used in previous releases, the following reason codes may also be 


returned: 

Return 

Code Meaning 

(hexadecimal) 

0304 The ddname was not specified by the calling routine. 

0308 The ddname specified by the calling routine was not found. 

0314 Restoring ddnames, as per this request, would have resulted in duplicate ddnames. 
Duplicate ddnames are not permitted. 

0318 Invalid characters are present in the ddname provided by the caller. 

031C Invalid characters are present in the membername provided by the caller. 

0320 Invalid characters are present in the dsname provided by the caller. 

0324 Invalid characters are present in the SYSOUT program name provided by the caller. 

0328 Invalid characters are present in the SYSOUT form number provided by the caller. 

032C An invalid SYSOUT class was specified by the caller. J 

0330 A membername was specified but the data set is not a partitioned data set. 

0334 The supplied data set name exceeded 44 characters in length. 

0338 The data set disposition specified by the caller is invalid. 

0348 

through 

034C Reserved. 


DAIRFAIL Routine (IKJEFF18) 


The DAIRFAIL routine analyzes return codes from SVC99 or DAIR, and 
performs one of the following functions, as requested: 


e Issue an error message when appropriate. 
e Only return the error message to the caller. 
e Issue an error message, as well as return the message to the caller. 


This process of returning the message(s) to the caller is referred to as extracting 
the message. 


DAIRFAIL may be invoked in either 24- or 31-bit addressing mode. When 


invoked in 31-bit addressing mode, DAIRFAIL may be passed input that resides : 
above 16 Mb in virtual storage. J 
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To invoke DAIRFAIL, link to IKJEFF18. When linking to IKJEFF18, provide 
the address of the following six-word parameter list in register 1: 


Offset 


Dec Hex 


Field Name 


DSECT - DFDSECTD 


DFS99RBP 
or 
DFDAPLP 


DFRCP 
DFJEFF02 


DSECT - DFDSECTD 


20 


C 


14 


DFS99RBP 
or 
DFIDP 


DFCPPLP 


DFBUFP 


DSECT - DFDSECT2 


256 


258 


260 


100 


102 


DFBUFS 
or 
DFBUFLI 


DFBUFO1 


DFBUFT1 


DFBUFL2 


DFBUF02 


DFBUFT2 
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Contents 


Address of the failing SVC99 request block or address of the failing 
DAIR parameter list. 


Address of a fullword containing either the SVC99 or DAIR return code. 


Address of a fullword containing either the entry point address of 
IKJEFFO2 (message writer routine) or zeros, if that address is unknown. 
This field (DFJEFF02) must always contain an address. 


Address of a two-byte area containing: 


Byte 1 Switches 
Bit0: O - PUTLINE issued 
1 - WTP issued 
Bit 1: 1 - Caller wants message extracted only. 
Bit 2: 1 - Caller wants message extracted as well as issued using 
PUTLINE or write-to-programmer (WTO). 
Byte 2 Caller identification number 
X‘01’ - DAIR 
X‘32’ - SVC99 


X‘33’ - SVC99 invoked by the FREE command 


Address of the CPPL. This is needed only when IKJEFF'18 is called 
with an SVC99 error and the user is not requesting a 
write-to-programmer message. 


Address of DFBUFS buffer if bit 2 (DFBUFSW) or bit 3 (DFBUFS2) of 
DFIDP is on. This is required when the message is to be extracted and 
returned to the caller. If the DFBUFSW is on, the message(s) will only 
be extracted. If DFBUFS2 is on, the message(s) will be issued as well as 
extracted and returned to the caller. It will be possible to extract the first 
level and one second level message. 


A 2 byte field that will contain the total length of the first level message, 
plus 4 bytes for length and offset fields. 


A 2 byte field containing the offset field. It will be set to zero when a 
message is extracted. 


A 251 byte buffer that will contain the text of the first level message 
extracted. If the message is greater than 251 bytes, the message will be 
truncated. 


A 2 byte field containing the total length of the first second level message 
plus four bytes. If there is no second level message, this field will contain 
HEX zeros. 


A 2 byte field containing the offset. It will be set to zero when a message 
is extracted. 


A 251 byte field that will contain the text of the first second level message 
extracted. If the message is greater than 251 bytes, the message will be 
truncated. 
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The IKJEFFDF macro may be used to map the fields in the parameter list. 
Specify the DFDSECT = YES option to obtain DSECT DFDSECTD instead of 
storage. Specify the DFSECT2= YES option to obtain DSECT DFDSECT2 
instead of storage. 


DFDSECT2 defines a storage area supplied by the caller. DAIRFAIL will return 
the requested informational message(s) in the associated buffers. It is not 
necessary to initialize these buffers. On return from DAIRFAIL, the buffers will 
contain the extracted message(s). 


DAIRFAIL allows the user to specify that a write-to-programmer message should 
be issued rather than the default PUTLINE routine. This is especially useful for 
analyzing errors occurring in a batch invocation of SVC99. If the high-order bit 
of the caller identification area (pointed to by DFIDP) is on, a 
write-to-programmer message will be issued instead of a PUTLINE. When the 
write-to-programmer feature is used, the address of the CPPL (DFCPPLP) need 
not be specified. 


The return code from DAIRFAIL is contained in register 15 as follows: 


0 - Message issued successfully 

4 - Invalid caller identification number 

8 - Message writer detected an error while attempting to issue a message 
12 - Extracted message buffer parameter list error 


GNRLFAIL/VSAMFAIL Routine (IKJEFF19) 


The GNRLFAIL/VSAMFAIL routine analyzes VSAM macro instruction failures, 
subsystem request (SSREQ) failures, parse service routine or PUTLINE failures, 
and ABEND codes, and issues an appropriate error message. It will insert the 
meaning of return codes from the VSAM/job entry subsystem interface. Other 
VSAM codes are explained in the VSAM Programmer's Guide. 


GNRLFAIL/VSAMFAIL may be invoked in either 24- or 31-bit addressing 
mode. When invoked in 31-bit addressing mode, GNRLFAIL/VSAMFAIL may 
be passed input that resides above 16 Mb in virtual storage. To invoke 
GNRLFAIL/VSAMPFAIL, link to IKJEFF19. When linking to IKJEFF19, 
provide the address of a pointer to the following parameter list in register 1: 


Offset 

Dec Hex Field Name Contents 

0 0 GFCBPTR Pointer to VSAM ACB if GFOPEN or GFCLOSE callerid. 
Pointer to VSAM RPL for other VSAM macro failures. Pointer 
to SSOB if GFSSREQ caller id. 

4 4 GFRCODE Error return code from register 15 or ABEND code if 
GFCALLID is GFABEND. 

8 8 GF02PTR Zero, or address of TSO message issuer routine (IKJEFF02) if 
already loaded. 

12 C GFCALLID ID for caller’s failing VSAM macro, or other failure. 
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Dec Hex 
GFCALLID = 
14 E 
15 F 

16 10 
20 14 
24 18 
26 1A 
28 1C 
32 20 
36 24 
40 28 


Offset 


Field Name 


Hexadecimal 
01 (GFCHECK) 


02 (GFCLOSE) 


03 (GFENDREQ) 


04 (GFERASE) 
05 (GFGET) 
06 (GFOPEN) 
07 (GFPOINT) 
08 (GFPUT) 

15 (GFPARSE) 


16 (GFPUTL) 
1F (GFABEND) 
20 (GFSSREQ) 
GFBITS 
GFKEYN08 
GFSUBSYS 
GFWTPSW 


GFRESV1 
GFCPPLP 


GFECBP 
GFDSNLEN 
GFPGMNL 
GFDSNP 


GFPGMNP 


GFRESV2 
GFRESV3 


Contents 


for VSAM CHECK macro error 
for VSAM CLOSE macro error 
for VSAM ENDREQ macro error 
for VSAM ERASE macro error 
for VSAM GET macro error 

for VSAM OPEN macro error 

for VSAM POINT macro error 
for VSAM PUT macro error 


for parse service routine error, other than a return code of 4 or 
20. 


for PUTLINE service routine error 
Issue ABEND message 
for Subsystem interface request (SSREQ) error 


Special processing switches 


1... ..... Caller not in key 0 or 8. 

.. .... Caller used VS2 VSAM/job entry subsystem interface. 

1, ..... Issue error message as write-to-programmer instead of 
PUTLINE. 

Reserved. 


Pointer to TMP’s CPPL control block (needed if PUTLINE 
issued, or to have command name inserted in the failure 
message). 


Pointer to ECB for PUTLINE (optional). 
Length of data set name. 
Length of program name. 


Pointer to data set name to insert in VSAMFAIL error messages 
(optional; default is ddname). 


Pointer to program name for insertion in all error messages 
(optional; default is ddname). 


Reserved. 


Reserved. 


The return code from GNRLFAIL is contained in register 15 as follows: 


0 
80 


Other 


- Message issued successfully 
- Invalid input parameter list (GFPARMS) for IKJEFF19. A message is also issued. 
- PUTLINE/PUTGET/IKJEFF02 message issuer error return code. 


The IKJEFFGF macro may be used to map the input parameter list. Specify the 
GFDSECT= YES option to obtain DSECT GFDSECTD instead of storage. 
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Chapter 11. Using BSAM or QSAM for Terminal I/O 


The basic sequential and queued sequential access methods provide terminal I/O 
support for programs operating under TSO. For a complete discussion of the use 
of BSAM and QSAM, see Data Management Services. 


The major benefit of using BSAM or QSAM to process terminal I/O under TSO 
is that programs using these access methods do not become TSO dependent or 
device dependent and may execute either under TSO or in the batch environment. 
Therefore, your existing programs that use BSAM or QSAM for I/O may be used 
under TSO without modification or recompilation. 


This section describes: 


The BSAM/QSAM macro instructions 

SAM terminal routines 

Record formats, buffering techniques, and processing modes 
Specifying the terminal line size 

End of file (EOF) for input processing 

Modifying DD statements for batch or TSO processing 


BSAM/QSAM Macro Instructions 


Some of the BSAM and QSAM access method routines have been modified to 
provide special services under TSO; others provide the same function that is 
provided in a batch environment. Those BSAM/QSAM macro instructions that 
are not relevant to terminal I/O act as no-ops. All of the BsAM/QSAM macro 
instructions, when executed in the batch environment, provide the non-terminal 
functions as explained in Data Management Macro Instructions. The 
BSAM/QSAM macro instructions must be issued 1n 24-bit addressing mode. 
Figure 11-1 shows the functions performed by the BSAM and QSAM macro 
instructions when used for terminal I/O. Following the table are more detailed 
explanations of the GET, PUT, PUTX, READ, WRITE, and CHECK macro 
instructions. 
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SAM Macro 
Instruction BSAM | QSAM | Terminal Interpretation 
BSP 4 xX NOP 


BUILD As in batch processing, the BUILD macro instruction causes a 
buffer pool to be constructed in a user-provided storage area. 


CHECK Takes an EODAD exit aftera READ EOF. NOP after a 
WRITE. 


CLOSE The CLOSE macro instruction frees the control blocks built to 
handle I/O and deletes the loaded SAM terminal] routines. 


CNTRL NOP 
REOV NOP 


FREEBUF As in batch processing, the FREEBUF macro instruction 
causes the control program to return a buffer to the buffer 
pool assigned to the specified data control block. : 


FREEPOOL As in batch processing, the FREEPOOL macro instruction 
causes an area of virtual storage, previously assigned as a 
buffer pool for a specified data control block, to be released. 


GET The GET macro instruction obtains data from the terminal via 
the TGET macro instruction. 


GETBUF As in batch processing, the GETBUF macro instruction causes 
the control program to obtain a buffer from the buffer pool 


assigned to the specified data control block, and to return the 
address of the buffer in a designated register. 


GETPOOL As in batch processing, the GETPOOL macro instruction 
causes a buffer pool to be constructed in a storage area 
provided by the control program. 


NOTE NOP 


OPEN The OPEN macro instruction loads the proper SAM terminal 
I/O routines and constructs the necessary control blocks. 


POINT NOP 
PRTOV NOP 


PUT The PUT macro instruction routes data to the terminal via the 
TPUT macro instruction. 


PUTX The PUTX macro instruction routes data to the terminal via 
the TPUT macro instruction. 


READ The READ macro instruction obtains data from the terminal 
via the TGET macro instruction. 


RELSE NOP 
SETPRT NOP 
TRUNC NOP 


WRITE The WRITE macro instruction routes data to the terminal via 
the TPUT macro instruction. 


Figure 11-1. BSAM/QSAM Macro Functions Under TSO 


SAM Terminal Routines 


The GET, PUT, PUTX, READ, WRITE, and CHECK macro instructions 
perform differently in terminal I/O than they do in the batch environment. 
Descriptions of these differences are presented here, but for a detailed explanation 
of how to use the macro instructions, see Data Management Macro Instructions. 
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GET 


PUT and PUTX 


READ 


The GET macro instruction causes a record to be retrieved from the terminal and 
placed in either the first buffer of the buffer pool control block (locate mode) or 
in a user specified area (substitute or move mode). In either case, the address of 
the record is returned in register 1. 


The record is moved via a TGET macro instruction which does not return control 
until the transfer of data completes. 


The input to the GET macro instruction consists of the DCB address and the 
user’s area address (omitted for locate mode). The output is edited (that is, 
specially-indicated characters are deleted from the eee Lowercase 
characters are folded to uppercase characters. 


When the terminal user types /*, end-of-file is indicated and control is passed to 
the problem program’s EODAD routine. If no EODAD routine is specified, the 
job will ABEND with a system code of 337. 


Both the PUT and the PUTX macro instructions cause a record to be written to a 
terminal. This transfer of data is accomplished with the TPUT macro instruction 
which does not return control until the transfer is completed. 


In locate mode, the first use of PUT or PUTX causes an address pointing to a 
buffer to be returned in register 1. The first record is placed in this buffer by the 
problem program and is written out when the next PUT or PUTX for the same 
data control block (DCB) is issued. Succeeding records are written in the same 
manner. The last record is written at CLOSE time. 


In move or substitute mode, the PUT or PUTX macro instruction moves a record 
from the user-specified work area to the terminal. You must supply the work 
area address to the PUT macro instruction. 


The input to the PUT and PUTX macro instruction consists of the DCB address 
and the user’s area address (omitted for locate mode). 


The READ macro instruction causes a block of data to be retrieved from the 
terminal and placed in a user-designated area in storage. This transfer of data is 
done via a TGET macro instruction which does not return control before the 
transfer is completed. The data is folded to uppercase. 


The input to the READ macro instruction consists of the string of parameters 
explained in Data Management Macro Instructions. 
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WRITE 


The WRITE macro instruction causes a block of data to be written from the ) 
user-specified area to the terminal. This transfer of data is done via a TPUT 
macro instruction which does not return control until the transfer is completed. 


The input to the WRITE macro instruction consists of the string of parameters 
explained in Data Management Macro Instructions. 


CHECK 


The CHECK macro instruction used after a WRITE macro instruction results in 
a NOP. When it is used after a READ macro instruction, it performs as a NOP 
unless an end of file (EOF) condition is encountered. The end of file signal from 
the terminal is /*. When end of file is encountered, CHECK takes the EODAD 

exit specified in the data control block. If no EODAD exit is specified, CHECK 
will cause the job to ABEND with a system code of 337. 


The input to the CHECK macro instruction is the address of the problem 
program’s data event control block (DECB). 


Record Formats, Buffering Techniques, and Processing Modes 


All record formats -- fixed (F), variable (V), and undefined (U) -- are supported 

under TSO. Before passing the data to the problem program, TSO automatically 

generates the first four bytes of control information for V format records coming 
in from the terminal. When you send V format records to the terminal, TSO J 
automatically removes the control information before writing the line. 


Control characters (ASCII or machine) are not supported under TSO. On output, 
they are removed before the data is sent to the terminal. On input, they are 
ignored. 


Both simple and exchange buffering techniques are supported, as are all four 
processing modes for the queued access method. 


Specifying Terminal Line Size 


If the LRECL and BLKSIZE fields are not specified in the DCB, the terminal 
line size default (or the line size the terminal user has specified via the 
TERMINAL command) is merged into the data control block fields as if it came 
from the label of the data set. 


For BSAM, BLKSIZE is used by TSO to determine the length of the text line it is 

to process. For both BSAM and QSAM, if the text entered from the terminal is 

shorter than the value specified for LRECL, and if F format is used, blanks are 

supplied on the right. For either access technique, if the text entered is longer 

than BLKSIZE or LRECL, the next GET or READ retrieves the remainder of 

the message. If the record generated by the problem program is longer than the , 
specified line size, multiple lines are displayed at the terminal. 2 
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C 


End-of-File (EOF) for Input Processing 


The sequential access method GET and CHECK terminal routines recognize /* 
from the terminal as an end-of-file (EOF). The EODAD exit in the data control 
block is taken for the EOF condition. If no EODAD exit has been specified, and 
an EOF has been signaled from the terminal, the job ABENDs with a system 
code of 337. 


Modifying DD Statements for Batch or TSO Processing 


TERM =TS, when added to a DD statement defining an input or an output data 
set, 1S ignored in the batch processing environment, but under TSO indicates to 
the system that the unit to which I/O 1s being addressed is a time sharing 
terminal. Thus a user who wants his job to run in either the foreground or the 
background could provide a DD statement as follows: 


| //oo1 | pp TERM=TS , SYSOUT=A 


In this example the output device is defined as a terminal under TSO processing, 
and as the SYSOUT device during batch processing. For a complete description 
of the TERM =TS parameter, see JCL. 
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Chapter 12. Using the TSO I/O Service Routines for Terminal I/O 


The TSO I/O service routines process terminal I/O requests initiated by the 
terminal monitor program (TMP), command processors (CPs), and other service 
routines. If you write your own command processors, or replace the 
IBM-supplied terminal monitor program with one of your own design, you should 
use the I/O service routines to process terminal I/O. 


The I/O service routines -- STACK, GETLINE, PUTLINE, and PUTGET -- 
offer the following features: 


1. They provide an interface between an I/O request and the TGET and TPUT 
supervisor calls. 


2. They provide a method of selecting sources of input other than the terminal. 
Requests for input can be directed to an in-storage list or data set as well as 
to the terminal. 


3. They provide a message formatting facility with which you can insert text 
segments into a basic message format, and display or inhibit the displaying of 
message identifiers. 


4. They process requests for more information (question-mark processing), and 
they analyze processing conditions to determine if I/O requests should be 
disregarded or honored. 


You pass control to the I/O service routines and indicate the functions you want 
performed by coding the operands you require in the list and the execute forms of 
the I/O service routine macro instructions. Each of the I/O service routine macro 
instructions (STACK, GETLINE, PUTLINE, and PUTGET) has a list and an 
execute form. 


The list form of each service routine macro instruction initializes the parameter 
blocks according to the operands you code into the macro instruction. 


The execute form is used to modify the parameter blocks and to provide linkage 
to the service routines, and can be used to set up the input/output parameter list. 
The input/output parameter list contains addresses required by the I/O service 
routines. 


Note: See the section “Processing Terminal Requests -- The TSO Service 


Routines” for information on the CALLTSSR macro interface to TSO service 
routines and a list of the DSECTs provided for TSO control blocks. 
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The Input/Output Parameter List 


The I/O service routines use two of the pointers contained in the command J 
processor parameter list: the pointer to the user profile table and the pointer to 

the environment control table. These addresses are passed to the service routines 

in another parameter list, the input/output parameter list (IOPL). The IOPL may 

reside above or below 16 Mb in virtual storage. If the IOPL resides above 16 

Mb, then the caller must run in 31-bit addressing mode. Before executing any of 

the TSO I/O macro instructions (GETLINE, PUTLINE, PUTGET, or STACK), 

you must provide an IOPL and pass its address to the I/O service routine. There 

are two ways you can construct an IOPL: 


1. You can build and initialize the IOPL within your code and place a pointer to 
it in the execute form of the I/O macro instruction. 


2. You can provide space for an IOPL (4 fullwords), pass a pointer to it, 
together with the addresses required to fill it, to the execute form of the I/O 
macro instruction, and let the I/O macro instruction build the IOPL for you. 


The input/output parameter list, as defined by the IKJIOPL DSECT, is a 
four-word parameter list. Figure 12-1 describes the contents of the IOPL. 


Number 
of Bytes Contents or Meaning 


IOPLUPT The address of the user profile table from the CPPLUPT field of the 
command processor parameter list. 


IOPLECT The address of the environment control table from the CPPLECT field of 


the CPPL. 
IOPLECB The address of the command processor’s event control block (ECB). The ) 
ECB is one word of storage, declared and initialized to zero by the 
command processor. Command processors with attention exits can post 


this ECB after an attention interruption to cause active service routines 
to exit. 


IOPLIOPB The address of the parameter block created by the list form of the I/O 
macro instruction. There are four types of parameter blocks, one for 
each of the I/O service routines: 


STACK parameter block (STPB) 
GETLINE parameter block (GTPB) 
PUTLINE parameter block (PTPB) 
PUTGET parameter block (PGPB) 


Figure 12-1. The Input/Output Parameter List 


The parameter block pointed to by the fourth word (IOPLIOPB) of the I/O 
parameter list is built and modified by the I/O service routine macros themselves. 
It is created and initialized by the list form of the I/O macro instruction, and 
modified by the execute form. Thus you can use the same parameter block to 
perform different functions. All you need to do is code different parameters in 
the execute forms of the macro instructions; these parameters provide those 
options not specified in the list form, and override those which were specified. 
Each of these parameter blocks -- the STACK, GETLINE, PUTLINE, and 
PUTGET parameter blocks -- is described in the separate sections on each of the 
I/O macro instructions. 
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Figure 12-2, an extension of Figure 10-17, summarizes the control block 
interfaces established between the terminal monitor program and an I/O service 
routine. 


Terminal Command 
Monitor Processor 
Program 


ATTACH 


Register | 


Figure 12-2. Control Block Interface Between the TMP and I/O Service Routine 


Passing Control to the I/O Service Routines 


The I/O service routines may be invoked in either 24-bit or 31-bit addressing 
mode. These routines execute in 31-bit addressing mode. Input may reside above 
or below 16 Mb in virtual storage, except for the list storage descriptor (LSD). 
The LSD must reside below 16 Mb in virtual storage. 


Service routines treat input addresses according to the addressing mode in which 
they are invoked. However, if you use the GETLINE macro, the addressing 
mode of the STACK macro will be used rather than your program’s addressing 
mode. Address values will be treated as 24-bit or 31-bit addressing mode 
depending on the addressing mode of the original issuer of the STACK macro for 
that element. 
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Pass control to an I/O service routine using the corresponding I/O macro 
instruction: 


Service Routine Macro Instruction 


STACK STACK 
GETLINE GETLINE 
PUTLINE PUTLINE 
PUTGET PUTGET 


You can use the DELETE macro instruction to release the storage area occupied 
by the load module when you have finished with your terminal I/O. Service of 
the TSO terminal I/O service routines are contained in the IKJPTGT load 
module. 


The I/O Service Routine Macro Instructions 


The I/O service routines -- STACK, GETLINE, PUTLINE, and PUTGET -- 
each perform a specific I/O function: 


STACK determines the source of input. 

GETLINE obtains a line of input. 

PUTLINE puts a line of output to the terminal. 

PUTGET puts a line to the terminal and gets a line in response. 


In order to perform these functions, the I/O macro instructions use the control 
blocks explained in the section “Processing Terminal Requests - The TSO Service 
Routines” and other, more individualized control blocks, the parameter blocks. 
Each of the I/O macro instructions has a list and an execute form. The list form 
sets up the parameter block required by that I/O service routine; the execute form 
can be used to set up the input output parameter list, and to modify the 
parameter block created by the list form of the macro instruction. 


The STACK, GETLINE, PUTLINE, and PUTGET macros may be issued in 
either 24- or 31-bit addressing mode. The corresponding I/O service routines 
execute in 31-bit addressing mode and return control in the same addressing mode 
in which they are invoked. Input may reside above or below 16 Mb in virtual 
storage, except for the list source descriptor (LSD). The LSD must reside below 
16 Mb. 


The parameter block required by each of the I/O service routines is different, and 
each one may be referenced through a DSECT. The parameter blocks and the 
DSECTS used to reference them are: 


The STACK parameter block referenced by IKJSTPB 
The GETLINE parameter block referenced by IKJGTPB 
The PUTLINE parameter block referenced by IKJPTPB 
The PUTGET parameter block referenced by IKJPGPB 


Each of these blocks is explained in the section describing the I/O macro 
instruction that builds it. 
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C 


STACK - Changing the Source of Input 


Use the STACK macro instruction to establish and to change the source of input. 
The currently active input source is described by the top element of the input 
stack, an internal pushdown list maintained by the I/O service routines. The first 
element of the input stack is initialized by the terminal monitor program (TMP), 
and cannot thereafter be changed or deleted. The IBM-supplied TMP initializes 
this first element to indicate the terminal as the current input source. The 
STACK service routine adds an element to the input stack or deletes one or more 
elements from it, and thereby changes the source of input for the other I/O service 
routines. 


A user can divide the input stack into substacks by creating barrier elements with 
the STACK macro instruction. A barrier element separates one group of stack 
elements, or substack, from another group of stack elements. Each substack can 
then be treated as a separate input stack. Use the barrier function of the STACK 
macro with the PUTGET or GETLINE SUBSTACK = YES services to determine 
when a barrier element is reached on the input stack. 


The STACK service routine saves the addressing mode of the program that 
invoked it. Address values are treated as 24-bit or 31-bit addressing mode, 

depending on the addressing mode of the original issuer of STACK for that 
element. 


This topic describes: 


The list and execute forms of the STACK macro instruction 
The sources of input 

The STACK parameter block 

The list source descriptor 

Return codes from STACK 


Coding examples are included where needed. 


The STACK Macro Instruction - List Form 


The list form of the STACK macro instruction builds and initializes a STACK 
parameter block (STPB), according to the operands you specify in the macro. 
The STACK parameter block indicates to the STACK service routine which 
functions you want performed. Figure 12-3 shows the list form of the STACK 
macro instruction; each of the operands is explained following the figure. 
Appendix A describes the notation used to define macro instructions. 
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[symbol] | STACK BARRIER=* 


TOP 
DELETE= |PROC 

ALL 

BARRIER 


PROCN , PROMPT 


STORAGE=(element address,}PROCL,PROMPT} )| ,MF=L 
SOURCE 


* 


DATASET= (INDD=add1,PROMPT,LIST 
MEMBER=addr3 
OUTDD=addr2,CNTL,SEQ 
CLOSE 


Figure 12-3. The List Form of the STACK Macro Instruction 


BARRIER =* 
Creates a barrier element (to divide the input stack into substacks) on top of 
the input stack. (Only a STACK DELETE= BARRIER request can delete 
a barrier element.) 


DELETE= 
Deletes an element or elements from the input stack. TOP, PROC, ALL, or 
BARRIER further defines the element to be deleted. 


TOP 
Deletes the topmost element (the element most recently added to the input 
stack). If the top element is a barrier element, STACK DELETE=TOP is 
a no-operation instruction. 


PROC 
Deletes the current procedure element from the input stack. If the top 
element is not a PROC element, deletes all elements down to, and including, 
the first PROC element. 


ALL 
Deletes all elements, except the bottom or first element, 
from the input stack. If one or more barrier elements exist on the input 
stack, deletes all elements down to, but not including, the first barrier 
element. 


BARRIER 
Deletes all elements down to, and including, the first barrier element. 


STORAGE = element address 
Adds an in-storage element to the input stack. The element address is the 
address of the list source descriptor (LSD). The LSD is a control block, 
pointed to by the STACK parameter block, which describes the in-storage 
list. The LSD must reside below 16 Mb in virtual storage. The in-storage 
element must be further defined as a SOURCE, PROCN, or PROCL list. 
SOURCE is the default. 
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PROMPT 
Specifies prompting by commands within a command procedure. PROMPT 
is used with the keywords PROCN and PROCL, which specify that the 
element to be added to the input stack is a command procedure. 


PROCN 
The element to be added to the input stack is a command procedure and the 
NOLIST option has been specified. 


PROCL } 
The element to be added to the input stack is a command procedure and the 
LIST option has been specified. Each line read from the command 
procedure is written to the terminal. 


SOURCE 
The element to be added to the input stack is an in-storage source data set. 


MF=L 
Indicates that this is the list form of the macro instruction. 


DATASET 
Supports the use of ACCOUNT in the background by expanding the 
facilities of dataset I/O for TSO commands to include reading from a 
SYSIN data set and writing to a SYSOUT dataset. To use the dataset 
function, the input and output files passed to the STACK service routine 
must be preallocated, either by a previously issued ALLOCATE command, 
a command processor going to dynamic allocation, a DD statement 
specified in the logon procedure, or, in the background, a user-supplied DD 
statement. 


Specifies that STACK use the bottom element in the input stack for I/O 
operations. This operand is the functional equivalent of TERM =*. 


INDD = addr] 
Specifies the input file name. 


PROMPT 
Allows prompting if prompting is also allowed on the bottom element of the 
Input stack. 


LIST 
Lists the input from the input stream. 


MEMBER = addr3 
Specifies an 8-character member name for a partitioned data set which was 
specified as the input file with the INDD operand. 


OUTDD = addr2 
Specifies the output file name. 


CNTL 
The output line has its own control character. 
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CLOSE 
Closes the data control blocks (DCBs) of the input stack. 


SEQ 
Tells dataset I/O not to remove sequence numbers. 


Note: In the list form of the macro instruction, only 


is required. When only STACK MF =L is specified, the STPB is zero¢d. The 
other operands and their sublists are optional because they may be supplied by 
the execute form of the macro instruction. 


The operands you specify in the list form of the STACK macro instruction set up 
control information used by the STACK service routine. The DATASET, 
STORAGE, and DELETE operands set bits in the STACK parameter block. 
These bit settings indicate to the STACK service routine which options you wish 
performed. 


The STACK Macro Instruction - Execute Form 


Use the execute form of the STACK macro instruction to perform the following 
three functions: 


1. To set up the input output parameter list (IOPL). 


2. To initialize those fields of the STACK parameter block not initialized by the 
list form of the macro instruction, or to modify those fields already initialized. 


3. To pass control to the STACK service routine which modifies the input stack. 
Figure 12-4 shows the execute form of the STACK macro instruction; each of the 


operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 
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[symbol] STACK [PARM=parm addr.][,UPT=upt addr. ] 
[,ECT=ect addr.][,ECB=ecb addr. ] 


BARRIER=* 


TOP 
DELETE= |PROC 

ALL 

BARRIER 


pce ry 
) 


STORAGE=(element addr.,} PROCL,PROMPT 
SOURCE 
TERM = «x 
INDD=add1,PROMPT,LIST 
DATASET= |MEMBER=addr 3 
OUTDD=addr2,CNTL, SEQ 
CLOSE 


(15) (1) 


(Gaia entry addr] | ,MF=(E,|/list ‘ane 


Figure 12-4. The Execute Form of the STACK Macro Instruction 


Note: TERM=* will be allowed by STACK to provide compatibility with 
existing modules when they are recompiled. 


PARM = parm addr 
Specifies the address of the 2-word STACK parameter block (STPB). It 
may be the address of the list form of the STACK macro instruction. The 
address is any address valid in an RX instruction, or the number of one of 
the general registers 2-12 enclosed in parentheses. This address will be 
placed in the input/output parameter list (IOPL). The STPB should be 
created using the list form of STACK. The STPB must be zeroed if no list 
options are specified. The STPB and IOPL (STPL) may be modified by 
STACK, so they should be in reentrant storage if used in a reentrant 
program. 


UPT = upt addr 
Specifies the address of the user profile table (UPT). This address may be 
obtained from the command processor parameter list pointed to by register 
one when the command processor is attached by the terminal monitor 
program. The address may be any address valid in an RX instruction or the 
number of one of the general registers 2-12 enclosed in parentheses. This 
address will be placed in the input/output parameter list (IOPL). 


ECT =ect addr 
Specifies the address of the environment control table (ECT). This address 
may be obtained from the CPPL pointed to by register 1 when the 
command processor is attached by the terminal monitor program. The 
address may be any address valid in an RX instruction or the number of 
one of the general registers 2-12 enclosed in parentheses. This address will 
be placed in the IOPL. 


ECB = ecb addr 
Specifies the address of an event control block (ECB). This address will be 
placed into the IOPL. You must provide a one-word event control block 
and pass its address to the STACK service routine by placing it into the 
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IOPL. The address may be any address valid in an RX instruction or the 
number of one of the general registers 2-12 enclosed in parentheses. 


TERM =* 
Adds a terminal element to the input stack. 


BARRIER =* 
Creates a barrier element (to divide the input stack into substacks) on top of 
the input stack. (Only a STACK DELETE= BARRIER request can delete 
a barrier element.) 


DELETE 
Deletes one or more elements from the input stack. TOP, PROC, ALL, or 
BARRIER specifies which element(s). 


TOP 
Deletes the topmost element (the element most recently added to the input 
stack). If the top stack element is a barrier element, STACK 
DELETE=TOP is a no-operation instruction. 


PROC 
Deletes the current procedure element from the input stack. If the top 
element is not a procedure element, deletes all elements down to and 
including the first procedure element. 


ALL 
Deletes all elements, except the bottom or first element, from the input 
stack. If one or more barrier elements exist on the input stack, deletes all 
elements down to, but not including, the first barrier element. 


BARRIER 
Deletes all elements on the input stack down to, and including, the first 
barrier element. 


STORAGE = element address 
Adds an in-storage element to the input stack. The element address is the 
address of the list source descriptor (LSD). The LSD is a control block, 
pointed to by the stack parameter block, which describes the in-storage list. 
The in-storage list must be further defined as a SOURCE, PROCN, or 
PROCL list. SOURCE is the default. 


SOURCE 
The element to be added to the input stack is an in-storage source data set. 


PROCN 
The element to be added to the input stack is a command procedure and the 
NOLIST option has been specified. 


PROCL 
The element to be added to the input stack is a command procedure and the 
LIST option has been specified. Each line read from the command 
procedure is written to the terminal. 
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PROMPT 
Specifies prompting by commands within a command procedure. PROMPT 
is used with the keywords PROCN and PROCL, which specify that the 
element to be added to the input stack is a command procedure. 


DATASET 
Supports the use of ACCOUNT in the background by expanding the 
facilities of dataset I/O for TSO commands to include reading from a 
SYSIN dataset and writing to a SYSOUT dataset. To use the dataset 
function, the input and output files passed to the STACK service routine 
must be preallocated, either by a previously issued ALLOCATE command, 
a command processor going to dynamic allocation, a DD statement 
specified in the logon procedure, or, in the background, a user-supplied DD 
statement. 


Specifies that STACK use the bottom element on the input stack for I/O 
operations. 


INDD = addr1 
Specifies the input file name. 


PROMPT 
Allows prompting if prompting is also allowed on the bottom element of the 
input stack. 


LIST 
Lists the input from the input stream. 


MEMBER = addr3 
Specifies the 8-character member name for the input file. 


OUTDD = addr2 
Specifies the output file name. 


CNTL 
The output line has its own control character. 


SEQ 
Tells dataset I/O not to remove sequence numbers. 


CLOSE 
Closes the data control blocks (DCBs) of the bottom element of the input 
stack. 


ENTRY entry address or (15) 
Specifies the entry point of the STACK service routine. The address may be 
any address valid in an RX instruction or (15) if the entry point address has 
been loaded into general register 15. If ENTRY is omitted, a LINK macro 
instruction will be generated to invoke the STACK service routine. 


MF=E 
Indicates that this is the execute form of the macro instruction. 
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listaddr 

(1) 
The address of the four-word input/output parameter list TOPL). This may 
be a completed IOPL that you have built, or it may be 4 words of declared 
storage that will be filled from the PARM, UPT, ECT, and ECB operands 
of this execute form of the STACK macro instruction. The address is any 
address valid in an RX instruction or (1) if the parameter list address has 
been loaded into general register 1. 


Note: In the execute form of the STACK macro instruction only the following 
operands are required: 


STACK | MF=(E, 


The PARM, UPT, ECT, and ECB operands are not required if you have built an 
IOPL in your own code. 


) 


list address 
(1) 


The other operands and their sublists are optional because they may be supplied 
by the list form of the macro instruction. 


The ENTRY operand need not be coded in the macro instruction. If it 1s not, a 
LINK macro instruction will be generated to invoke the I/O service routine. 


The operands you specify in the execute form of the STACK macro instruction 
are used to set up control information used by the STACK service routine. You 
can use the PARM, UPT, ECT, and ECB operands of the STACK macro 
instruction to complete, build, or alter an IOPL. The DATASET, STORAGE, 
and DELETE operands set bits in the STACK parameter block. These bit 
settings indicate to the STACK service routine which options you want. 


Sources of Input 
The input sources provided are defined as follows: 
1. Terminal 
If the terminal is specified in the STACK macro instruction as the input 
source, all input and output requests through GETLINE, PUTLINE, and 
PUTGET are read from the terminal and written to the terminal. The user at 
the terminal controls TSO by entering commands; the system processes these 


commands as they are entered and returns to the user for another command. 


When an online job is running, the first element in the input stack is a 
terminal element. 


2. In-Storage List 
An in-storage list can be either a list of commands or a source data set. It 
may contain variable-length records (with a length header) or fixed-length 


records (no header and all records the same length). In either case, no one 
record on an in-storage list may exceed 256 characters. 
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When a job is running in the background, the first element in the input stack 
is a data set element. 


An in-storage list and its processing are specified by setting the STORAGE 
operand type to PROCN, PROCL, or SOURCE. 


e PROCN or PROCL - Indicates that the in-storage list is a command 
procedure, a list of commands to be executed in the order specified. If you 
specify PROCN, requests through GETLINE are read from the in-storage 
list, but PROMPT requests from the executing command processor are 
suppressed. MODE messages, those messages normally sent to the terminal 
requesting entry of a command or a sub-command, are not sent but a 
command is obtained from the in-storage list. If the PROCL option is 
specified, the command is displayed at the terminal as it is read from the list. 


SOURCE - Indicates that the in-storage list is a source data set. Requests 
through GETLINE are read from the in-storage list, but PROMPT requests 
from the executing command processor are honored if prompting is allowed, 
and a line is requested from the terminal. MODE messages are handled the 
same way as with PROCN or PROCL. No LIST facility is provided with 
SOURCE records. 


Building the STACK Parameter Block 


When the list form of the STACK macro instruction expands, it builds a five 
word STACK parameter block (STPB). The list form of the macro instruction 
initializes this STPB according to the operands you have coded. This initialized 
block, which you may later modify with the execute form of the macro 
instruction, indicates to the I/O service routine the functions you want performed. 


By using the list form of the macro instruction to initialize the block, and the 
execute form to modify it, you can use the same STPB to perform different 
STACK functions. Keep in mind, however, that if you specify an operand in the 
execute form of the macro instruction, and that operand has a sublist as a value, 
the default values of the sublist will be coded into the STPB for any of the sublist 
values not coded. If you do not want the default values, you must code each of 
the values you require, each time you change any one of them. 


For example, if you coded the list form of the STACK macro instruction as 
follows: 


STACK STORAGE=(element address,PROCN) ,MF=L 


and then overrode it with the execute form of the macro instruction as follows: 


STACK STORAGE=(new element address), 
MF=(E,list address) 


The element code in the STACK parameter block would default to SOURCE, the 
default value. If the new in-storage list was another PROCN list, you would have 
to respecify PROCN in the execute form of the macro instruction. 
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The STACK parameter block is defined by the IKJSTPB DSECT. Figure 12-5 ‘ 
describes the contents of the STPB. ) 


umber 
Y —_ Contents or Meaning 


Operation code: A flag byte which describes the operation to be 
performed. 


One element is to be added to the top of the input stack. 
The top element is to be deleted from the input stack. 


The current procedure is to be deleted from the input stack. If the top 
element is not a PROC element, all elements down to and including the 
first PROC element encountered are deleted, except the bottom 
element. 


All elements except the bottom one (the first element) dre to be deleted. 
Reserved bits. 


Element code: A flag byte describing the element to be added to the 
input stack. 


A terminal element. 

An in-storage element. 

Input DD name present. 

Output DD name present. 

The in-storage element is an EXEC command element. 
Prompting is allowed from the PROC element. 

The in-storage element is a source element. 

The in-storage element is a procedure element. 

The list option (PROCL) has been specified. 


Reserved. 
DATASET operation. 


Reserved. 

Do not remove sequence numbers. 
User-specified CNTL. 

Close option. 


The address of the list source descriptor (LSD). An LSD describes an 
in-storage list. If the input source is the terminal, or if DELETE has 
been specified, this field will contain zeros. 


STPBALSD 


STPBINDD 
STPBODDN 
STPBMBRN 


Pointer to input DD name. 


Pointer to output DD name. 


Pointer to membername. 


Figure 12-5. The STACK Parameter Block 


If the DATASET or DELETE operands have been coded in the STACK macro 
instruction, the second word of the stack parameter block will contain zeroes and 
the control block structure will end with the STPB. Figure 12-6 describes this 
condition. 
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Terminal Command STACK 
Monitor Processor Service 
Program Routine 


Figure 12-6. STACK Control Blocks: No In-Storage List 


To add an in-storage list element to the input stack, you must describe the 
in-storage list and pass a pointer to it to the STACK I/O service routine. You do 
this by building a list source descriptor (LSD). The LSD must reside below 16 
Mb in virtual storage. 


Figure 12-7 is an example of the code required to add the terminal to the input 
stack as the current input source. In this example, the execute form of the 
STACK macro instruction is used to build the input/output parameter list for 
you. The list form of the STACK macro instruction expands into a STACK 
parameter block, and its address is passed to the execute form of the macro 
instruction as the PARM operand address. 
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Figure 12-7. Coding Example - STACK Specifying the Terminal as the Input Source 


This sequence of code does not make use of the IKJCPPL DSECT to access the 


command processor parameter list, nor does it provide reenterable code. 


Building the List Source Descriptor (LSD) 


A list source descriptor (LSD) is a four-word control block that describes the 
in-storage list pointed to by the new element you are adding to the input stack. 
Note that the LSD must reside below 16 Mb in virtual storage. If you are 
designating the terminal as the input source, no LSD is necessary and the second 
word of the STPB will be zero. If you specify STORAGE as the input source in 
the STACK macro instruction, your code must build an LSD, and place a pointer 


to it as a sublist of the STORAGE operand. The LSD must begin ona 


doubleword boundary, and must be created in the shared subpool designated by 
the terminal monitor program; the IBM-supplied TMP shares subpool 78 with the 
command processors. The LSD is defined by the IKJLSD DSECT. Figure 12-8 


describes the contents of the LSD. 


12-16 TSO/E Guide to Writing a TMP or a CP 
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umber 
ripe | meu | conser ting 


LSDADATA | The address of the in-storage list. 


LSDRCLEN | The record length if the in-storage list contains fixed-length records. 
Zero if the record lengths are variable. 


LSDTOTLN | The total length of the in-storage list; the sum of the lengths of all 
records in the list. 


LSDANEXT | Pointer to the next record to be processed. Initialize this field to the 
address of the first record in the list. The field is updated by the 
GETLINE and PUTGET service routines. 


LSDRSVRD Reserved. 


Figure 12-8. The List Source Descriptor 


If you have provided an LSD, and specified the STORAGE operand in the 
STACK macro instruction, the second word of the stack parameter block will 
contain the address of the LSD, and the STACK control block structure will look 
like Figure 12-9. 
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Terminal Command 
Monitor ATTACH Service 


Program Routine 


Reg. 1 Reg. 1 


CPPL IOPL 


STPB 


LSD 


LS'> ADATA 


In-Storage List 


Figure 12-9. STACK Control Blocks: In-Storage List Specified 
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Figure 12-10 is an example of the code required to use the STACK macro 


instruction to place a pointer to an in-storage list on the input stack. 


In the example, the GETMAIN macro instruction is used to obtain storage in 
subpool 78 for the list source descriptor and the in-storage list itself. The execute 
form of the STACK macro instruction initializes the input/output parameter list 
required by the STACK service routine. The list form of the STACK macro 
instruction expands into a STACK parameter block, and its address is passed to 
the STACK service routine via the PARM operand in the execute form of the 


STACK macro instruction. 
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Figure 12-10 (Part 1 of 3). Coding Example - STACK Specifying an In-Storage List as the Input Source 
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Figure 12-10 (Part 2 of 3). Coding Example - STACK Specifying an In-Storage List as the Input Source 
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Figure 12-10 (Part 3 of 3). Coding Example - STACK Specifying an In-Storage List as the Input Source 


Return Codes from STACK 


When it returns to the program which invoked it, the STACK service routine will 
provide one of the following return codes in general register 15: 


Code Meaning 

0 STACK has completed successfully. 

4 One or more of the parameters passed to STACK were invalid. 
8 INDD was specified and the file could not be opened. 


12 OUTDD was specified and the file could not be opened. 
16 MEMBER was specified but was not in the partitioned data set specified by INDD. 
20 GETMAIN failure (only possible if MEMBER is specified). 
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GETLINE - Getting a Line of Input 


You use the GETLINE macro instruction to obtain all input lines other than J 
commands or subcommands, and prompt message responses. Commands, 

subcommands, and prompt message responses should be obtained with the 

PUTGET macro instruction. 


When a GETLINE macro instruction is executed, a line is obtained from the 
current source of input (the terminal or an in-storage list) or optionally, from the 
terminal, regardless of the current source of input. The processing of the input 
line varies according to several factors. Included in these factors are the source of 
input, and the options you specify for logical or physical processing of the input 
line. The GETLINE service routine determines the type of processing to be 
performed from the operands coded in the GETLINE macro instruction, and 
returns a line of input. 


This topic describes: 


The list and execute forms of the GETLINE macro instruction 
The sources of input 

The GETLINE parameter block 

The input line format 

Examples of GETLINE 

Return codes from GETLINE 


The GETLINE Macro Instruction - List Form 


The list form of the GETLINE macro instruction builds and initializes a J 
GETLINE parameter block (GTPB), according to the operands you specify in the 

GETLINE macro. The GETLINE parameter block indicates to the GETLINE 

service routine which functions you want performed. Figure 12-11 shows the list 

form of the GETLINE macro instruction; each of the operands is explained 

following the figure. Appendix A describes the notation used to define macro 

instructions. 


[symbol] | GETLINE INPUT=(| ISTACK ||,LOGICAL |) 
TERM ; PHYSICAL 


meee USS (a }? en 


ASIS NOWAIT 


, SUBSTACK= (| NO 
YES 


Figure 12-11. The List Form of the GETLINE Macro Instruction 


INPUT = 
Indicates that an input line is to be obtained. That input line is further 
described by the INPUT sublist operands ISTACK, TERM, LOGICAL, 
and PHYSICAL. ISTACK and LOGICAL are the default values. 


ISTACK 


Obtain an input line from the currently active input source indicated by the 
input stack. 
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TERM 
Obtain an input line from the terminal. If TERM 1s coded in the macro 
instruction, the input stack is ignored and regardless of the currently active 
input source, a line 1s returned from the terminal. 


LOGICAL 
The input line to be obtained 1s a logical line; the GETLINE service routine 
is to perform logical line processing. 


PHYSICAL 
The input line to be obtained 1s a physical line. The GETLINE service 
routine need not inspect the input line. 


Note: If the input line you are requesting is a logical line coming from the 
input source indicated by the input stack, you need not code the INPUT 
operand or its sub-list operands. The input line description defaults to 
ISTACK, LOGICAL. 


TERMGET 
Specifies the TGET options requested. GETLINE issues a TGET SVC to 
bring in a line of data from the terminal. This operand indicates to the 
TGET SVC which of the TGET options to use. The TGET options are 
EDIT or ASIS, and WAIT or NOWAIT. The default values are EDIT and 
WAIT. 


EDIT 
Specifies that in addition to minimal editing (see ASIS), the buffer is to be 
filled out with trailing blanks. 


ASIS 
Specifies that minimal editing is to be done as follows: 


1. Transmission control characters are removed. 

2. The line of input is translated from terminal code to EBCDIC. 
3. Line deletion and character deletion editing is performed. 

4. Lune feed and carrier return characters, if present, are removed. 


No line continuation checking is done. 


WAIT 
Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction only after an input message has been read. 


NOWAIT 
Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction whether or not a line of input is available. If 
a line of input is not available, a return code of 12 decimal is returned in 
register 15 to the command processor. 
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MF=L 
Indicates that this is the list form of the macro instruction. 


SUBSTACK = 
For CLIST processing, YES indicates that normal stack operations continue 
until GETLINE reaches a barrier element. GETLINE then passes the caller 
a return code indicating that CLIST processing completed. The barrier 
element remains on the stack until the caller explicitly deletes it. NO is the 
default value and indicates that the barrier feature is not used. 


Note: Ifacaller issues GETLINE without SUBSTACK = YES, and a 
barrier element exists on the input stack, normal stack operations continue 
until GETLINE reaches a barrier element. In foreground mode, GETLINE 
then treats the barrier element as a terminal element. In background mode, 
GETLINE passes an end-of-data return code to the caller. Processing 
continues in this manner until the caller explicitly deletes the barrier 
element. 


Note. In the list form of the macro instruction, only 


is required. The other operands and their sublists are optional because they may 
be supplied by the execute form of the macro instruction, or automatically 
supplied if you want the default values. 


The operands you specify in the list form of the GETLINE macro instruction set 
up control information used by the GETLINE service routine. The INPUT and 
TERMGET operands set bits in the GETLINE parameter block to indicate to the 
GETLINE service routine which options you want performed. 


The GETLINE Macro Instruction - Execute Form 


Use the execute form of the GETLINE macro instruction to perform the 
following three functions: 


1. You may use it to set up the input/output parameter list OPL). 


2. You may use it to initialize those fields of the GETLINE parameter block 
(GTPB) not initialized by the list form of the macro instruction, or to modify 
those fields already initialized. 


3. You use it to pass control to the GETLINE service routine which gets the 
line of input. 


Figure 12-12 shows the execute form of the GETLINE macro instruction; each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 
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[symbol] | GETLINE PARM=parameter address][,UPT=upt address) 
pena address][,ECB=ecb address) 


, LNPUT=(] ISTACK] |,LOGICAL | ) 
TERM ,PHYSICAL 


ASIS NOWAIT 


,ENTRY=] entry address ai ta address| ) 


(15) (1) 


, SUBSTACK=(} NO | ) 
YES 


| 
a (gpa | . »WAIT } | 
| 
| 


Figure 12-12. The Execute Form of the GETLINE Macro Instruction 


PARM = parameter address 
Specifies the address of the 2-word GETLINE parameter block (GTPB). It 
may be the address of a list form GETLINE macro instruction. The 
address is any address valid in an RX instruction, or the number of one of 
the general registers 2-12 enclosed in parentheses. This address will be 
placed in the input/output parameter list (IOPL). 


UPT = upt address 
Specifies the address of the user profile table (UPT). You may obtain this 
address from the command processor parameter list pointed to by register 1 
when the command processor is attached by the terminal monitor program. 
The address may be any address valid in an RX instruction or the number 
of one of the general registers 2-12 enclosed in parentheses. This address 
will be placed in the IOPL. 


ECT =ect address 
Specifies the address of the environment control table (ECT). You may 
obtain this address from the CPPL pointed to by register 1 when the 
command processor is attached by the terminal monitor program. The 
address may be any address valid in an RX instruction or the number of 
one of the general registers 2-12 enclosed in parentheses. This address will 
be placed into the IOPL. 


ECB =ecb address 
Specifies the address of an event control block (ECB). You must provide a 
one-word event control block and pass its address to the GETLINE service 
routine by placing it into the IOPL. The address may be any address valid 
in an RX instruction or the number of one of the general registers 2-12 
enclosed in parentheses. This address will be placed into the IOPL. 


INPUT = 
Indicates that an input line is to be obtained. This input line is further 
described by the INPUT sublist operands ISTACK, TERM, LOGICAL, 
and PHYSICAL. ISTACK and LOGICAL are the default values. 


ISTACK 


Obtains an input line from the currently active input source indicated by the 
input stack. 
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TERM 
Obtains an input line from the terminal. If TERM is coded in the macro 
instruction, the input stack will be ignored and regardless of the currently 
active input source, a line is returned from the terminal. 


LOGICAL 
The input line to be obtained is a logical line; the GETLINE service routine 
is to perform logical line processing. A logical line is a line that has had 
additional processing by the GETLINE service routine before it is returned 
to the requesting program. 


PHYSICAL 
The input line to be obtained is a physical line. A physical line is a line that 
is returned to the requesting program exactly as it is received from the input 
source. 


Note: If the input line you are requesting is a logical line coming from the 
input source indicated by the input stack, you need not code the INPUT 
operand or its sublist operands. The input line description defaults to 
ISTACK, LOGICAL. 


TERMGET 
Specifies the TGET options requested. GETLINE issues a TGET SVC to 
bring in a line of data from the terminal. This operand indicates to the 
TGET SVC which of the TGET options to use. The TGET options are 
EDIT or ASIS, and WAIT or NOWAIT. The default values are EDIT and 
WAIT. 


EDIT 
Specifies that in addition to minimal editing (see ASIS), the input buffer is 
to be filled out with trailing blanks. All station control characters are 
suppressed from data. 


ASIS 
Specifies that minimal editing is to be done by the TGET SVC. The 
following editing functions will be performed by TGET: 


1. Station control characters remain in the data. 

2. The line of input is translated from terminal code to EBCDIC. 
3. Line deletion and character deletion editing are performed. 

4. Line feed and carrier return characters, if present, are removed. 


No line continuation checking is done. 


WAIT 
Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction, only after an input message has been read. 


NOWAIT 
Specifies that control is to be returned to the routine that issued the 
GETLINE macro instruction whether or not a line of input is available. If 
a line of input is not available, a return code of 12 decimal is returned in 
register 15 to the command processor. 
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ENTRY = entry address or (15) CLKIGE re) 
Specifies the entry point of the GETLINE service routine. If ENTRY is 
omitted, a LINK macro instruction will be generated to invoke the 
GETLINE service routine. The address may be any address valid in an RX 
instruction or (15) if the entry point address has been loaded into general 
register 15. 


MF=E 
Indicates that this is the execute form of the macro instruction. 


listaddr 

(1) 
The address of the four-word input/output parameter list (IOPL). This may 
be a completed IOPL that you have built, or it may be 4 words of declared 
storage that will be filled from the PARM, UPT, ECB, and ECT operands 
of this execute form of the GETLINE macro instruction. The address is 
any address valid in an RX instruction or (1) if the parameter list address 
has been loaded into general register 1. 


SUBSTACK = 
For CLIST processing, YES indicates that normal stack operations continue 
until GETLINE reaches a barrier element. GETLINE then passes the caller 
a return code indicating that CLIST processing completed. The barrier 
element remains on the stack until the caller explicitly deletes it. NO is the 
default value and indicates that the barrier feature is not used. 


Note: If the caller issues GETLINE without SUBSTACK = YES, and a 
barrier element exists on the input stack, normal stack operations continue 
until GETLINE reaches a barrier element. In forground mode, GETLINE 
then treats the barrier element as a terminal element. In background mode, 
GETLINE passes an end-of-data return code to the caller. Processing 
continues in this manner until the caller explicitly deletes the barrier 
element. 


Note: In the execute form of the GETLINE macro instruction only the following 
is required: 


sales ae: address 
(1) 


The PARM, UPT, ECT, and ECB operands are not required if you have built 
your IOPL in your own code. The other operands and their sublists are optional 
because you may have supplied them in the list form of the macro instruction or 
in a previous execution of GETLINE, or because you are using the default values. 


) 


The ENTRY operand need not be coded in the macro instruction. If it is not, a 
LINK macro instruction will be generated to invoke the I/O service routine. 


The operands you specify in the execute form of the GETLINE macro instruction 
are used to set up control information used by the GETLINE service routine. 

You can use the PARM, UPT, ECT, and ECB operands of the GETLINE macro 
instruction to build, complete, or modify an IOPL. The INPUT and TERMGET 
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operands set bits in the GETLINE parameter block. These bit settings indicate to 
the GETLINE service routine which options you want performed. 


Sources of Input 


There are two sources of input provided; they are the terminal, and an in-storage 
list. 


1. Terminal: Input comes from the terminal under either of the following 
conditions: 


e You have specified the terminal as the input source by including the 
TERM operand in the GETLINE macro instruction. 


e You have specified the current element of the input stack by including the 
ISTACK operand in the GETLINE macro instruction, and the current 
element is a terminal element. 


If you specify terminal as the input source, you have the option of requesting 
the GETLINE service routine to process the input as a logical or physical line 
by including the LOGICAL or the PHYSICAL operand in the macro 
instruction. LOGICAL is the default value. 


Physical Line Processing: A physical line is a line that is returned to the 
requesting program exactly as it is received from the input source. The 
contents of the line are not inspected by the GETLINE service routine. 


Logical Line Processing: A logical line is a line that has undergone additional 
processing by the GETLINE service routine before it is returned to the 
requesting program. If logical line processing is requested, each line returned 
to the routine that issued the GETLINE is inspected to see if the last 
character of the line is a continuation mark (a dash ‘-’ or a plus‘+’). A 
continuation mark signals GETLINE to get another line from the terminal 
and to concatenate that line with the line previously obtained. The 
continuation mark is overlaid with the first character of the new line. 
However, ASIS does not recognize line continuation. 


2. In-Storage List: If the top element of the input stack is an in-storage list, and 
you do not specify TERM in the GETLINE macro instruction, the line will 
be obtained from the in-storage list. The in-storage list is a resident data set 
that has been previously made available to the I/O service routines with the 
STACK service routine. The STACK service routine saves the addressing 
mode of the program that invoked it. Address values will be treated as 24-bit 
or 31-bit addressing mode depending on the original issuer of STACK for 
that element. No logical line processing is performed on the lines because It 1s 
assumed that each line in the in-storage list is a logical line. It is also 
assumed that no single record has a length greater than 256 bytes. 
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End of Data Processing 


If you issue a GETLINE macro against an in-storage list from which all the 
records have already been read, GETLINE senses an end of data (EOD) 
condition. GETLINE deletes the top element from the input stack and passes a 
return code of 16 in register 15. Return code 16 indicates that no line of input 
has been returned by the GETLINE service routine. You can use this EOD code 
(16) as an indication that all input from a particular source has been exhausted 
and no more GETLINE macro instructions should be issued against this input 
source. If you reissue a GETLINE macro instruction against the input stack after 
a return code of 16, a record will be returned from the next input source indicated 
by the input stack. You can identify the source of this record by the return code 
(0 = terminal, 4 = in-storage). 


Building the GETLINE Parameter Block 


When the list form of the GETLINE macro instruction expands, it builds a two 
word GETLINE parameter block (GTPB). The list form of the macro instruction 
initializes this GIPB according to the operands you have coded in the macro 
instruction. This initialized block, which you may later modify with the execute 
form of the macro instruction, indicates to the GETLINE service routine the 
function you want performed. 


You must supply the address of the GITPB to the execute form of the GETLINE 
macro instruction. For non-reenterable programs you can do this simply by 
placing a symbolic name in the symbol field of the list form of the macro 
instruction, and passing this symbolic name to the execute form of the macro 
instruction as the PARM value. The GETLINE parameter block is defined by 
the IKJGTPB DSECT. Figure 12-13 describes the contents of the GTPB. 
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Control flags. These bits describe the requested input line to the 
GETLINE service routine. 


The input line is a logical line. 
The input line is a physical line. 


The input line is to be obtained from the current input source indicated 
by the input stack. 


The input line is to be obtained from the terminal. 
Reserved bits. 


Reserved. 


TGET options field. These bits indicate to the TGET SVC which of the 
TGET options you want to use. 


Always set to | for TGET. 


WAIT processing has been requested. Control will be returned to the 
issuer of GETLINE only after an input message has been read. 


NOWAIT processing has been requested. Control will be returned to 
the issuer of the GETLINE macro instruction whether or not a line of 
input is available. 


EDIT processing has been requested. In addition to the editing 
provided by ASIS processing, the input buffer is to be filled out with 
trailing blanks to the next doubleword boundary. 


01 ASIS processing has been requested. (See the ASIS operand of the 
GETLINE macro instruction description.) 


XX. XX.. Reserved bits. 


Byte 2 

XXXX XXXX Reserved. 

GTPBIBUF | The address of the input buffer. The GETLINE service routine fills this 
field with the address of the input buffer in which the input line has 
been placed. 


Figure 12-13. The GETLINE Parameter Block 


Input Line Format - The Input Buffer 


The second word of the GETLINE parameter block contains zeros until the 
GETLINE service routine returns a line of input. The service routine places the 
requested input line into an input buffer beginning on a doubleword boundary 
located in subpool 1. It then places the address of this input buffer into the 
second word of the GIPB. The input buffer belongs to the command processor 
that issued the GETLINE macro instruction. The buffers returned by GETLINE 
are automatically freed when your CP relinquishes control. You may free the 
input buffer with the FREEMAIN macro instruction after you have processed or 
copied the input line. 


Regardless of the source of input, an in-storage list or the terminal, the input line 
returned to the command processor by the GETLINE service routine is in a 
standard format. All input lines are in a variable length record format with a 
fullword header followed by the text returned by GETLINE. Figure 12-14 shows 
the format of the input buffer returned by the GETLINE service routine. 
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Figure 12-14. Format of the GETLINE Input Buffer 


The two-byte length field contains the length of the input line including the 
header length (4 bytes). You can use the length field to determine the length of 
the input line to be processed, and later, to free the input buffer with the R-form 
of the FREEMAIN macro instruction. 


The two-byte offset field is always set to zero on return from the GETLINE 
service routine. 


Figure 12-15 shows the GETLINE control block structure after the GETLINE 
service routine has returned an input line. 
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Terminal Command GETLINE 
Monitor Processor Service 
Program Routine 


Figure 12-15. GETLINE Control Blocks - Input Line Returned 


Examples of GETLINE 


Figure 12-16 is an example of the code required to execute the GETLINE macro 
instruction. In this example two execute forms of the GETLINE macro 
instruction are issued. The first one builds the IOPL, and uses the parameters 
initialized by the list form of the macro instruction to get a physical line from the 
terminal with the NOWAIT and ASIS options. 


In the second execution of the GETLINE macro instruction, the same IOPL is 
used, but the GETLINE options are changed explicitly from TERM to ISTACK 
and from NOWAIT to WAIT, and by default from PHYSICAL to LOGICAL 
and from ASIS to EDIT. 


Notice also that the IKJCPPL DSECT is used to map the command processor 


parameter list, and the IKJGTPB DSECT is used to map the GETLINE ) 
parameter block. 
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Figure 12-16 (Part 1 of 2). 


|= 


misisie, mit el {lst — 
Sl=lx=/ Im [| me 


mee 
| 


Ee SRR SC ae ICOWITIAITINIS| {al POITIER! rio. Iriel ft 
|_| ICOMM|AINID ROCES SOR PARAMETER! ieee! 
220 oA A 


SAB LIIT 


AIRE Ach 


R 


p) 


A 
T 


if 
R 
i 
& 


ue 
Bo Lon bg 


eV EE ec 

NIEXIECUTIE| FORM, [0} 
PIHIY|S!/ (CIA\L| |d 
|AIND If 


yal eel 
LTE TT el TT | | BL ICIP iP iuipir: | | 
ee CINE esi ei ETE 
| LA CEPLECT _ PLATE Tie ADDRES 9 


—< 
~* 
‘mh ) 


= 
Hs 
is 


im] 
a 
7 
s) 
eee 
aE 
See | 


martes 
~ oO 
se 
“01M : 
a>) 


aia 
= 
im 
Lau) 
ol 


Es) 
m 


= 
x= 
[—~| >< 


a 
a 
<a 
bas) 


S 


— 


See 
ON OO] 
=) is 


MAL NTO 
if pees 
Ha PESTO ES ae CIPIPL . 
DRESSABNILITY OR CPDL | 
PERERA REE RESAE ESSA Eee ee: 
GEIL INE] MACRO] INS TIRUCT | 
OM) (THE! [TIEIRIMI/INIAIL.. IT'S! [EXEICUITIE: | | 
NUTTALL PZ E'S! TIME! | NPT] [OUTPlUT] PAR AME TIEIR | | | 
eRe ETRE R ee eee eee 
Cee eee ele ee ETT Pee Seis ala im 
PILIACIE| (THE! [A[DIDIRIE|S|S! OF] TIE, |VIPIT| | 
INITIO} JA) IRIEVGIISITIE[R-| | | | Li] | ty Lt | 


R. 


— 


| IHN TIO) IA IRIEIGI! ISITIENR].| | | | | | 


LIADISD| TILT TT TT TTT TT Et TT 
AAHAARAANOOEHAN SHRAE BAGEL AEE 
a ee UICTION| |UISIES| | | 

NIOIWAl! IT] [O/PIE[RIA N NDS CODE [| {tw | | 


“ 


|AIS|HS|s|_| [AIN 


THE CETLIME MACRO. TMS TRUCI 1 

PEE EGE eee ie ctalal 
 RETURRED 1 INE FROM MIT 
Be gee SRERRE 


Kew we I) 
SEAEUSHGETABSEIAMEEHGEE AASAAnE 
BILIO(CK] | | | | SEIT 


TP|Bl-| | | | |} ||| PEEL 
BTBUF| ‘| [eY| THE ADDRESS" OF THE LTWE 
cre Saal tebe eI Tena OT aero ee Ia ale 
BERR RNE Ca RARER AME AEE. 
cE TT Te AR tt 
af OM! |THIE| CIURRIENTILY| | | | | 


Al (C{/ NIE] |FIR 
ce U/SIE'S|_[TiMIE| |T/O/PIL| IC|ONSITIRIUICIT/E|D._[Bly| | | | | 
ON, [OIF] [THe] [GlE(ric IIe] [MAICIRIO[ [INisirikiuicirioI[, | | IT | 


aS 
o|— 


HIE 


a 
sim 
| 
ea 
= 
O! 
HL 
i=] 
E2) 
Gul 
[%) 
%) 
ele 
fed 
aoe 
ee | 
a 
fal 
SS 
Eas) 
id 
= 
[rr] 


Coding Example - Two Executions of GETLINE 
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Figure 12-16 (Part 2 of 2). Coding Example - Two Executions of GETLINE 
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Return Codes from GETLINE 


When it returns to the program that invoked it, the GETLINE service routine 
returns one of the following codes in general register 15: 


Code Meaning 
0 GETLINE has completed successfully. The line was obtained from the terminal. 
4 GETLINE has completed successfully. The line was returned from an in-storage list. 


8 The GETLINE function was not completed. An attention interruption occurred during 
GETLINE processing, and the user’s attention routine turned on the completion bit in the 


communications ECB. 
12 oll 


The NOWAIT option was specified and no line was obtained. 
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16 EOD - An attempt was made to get a line from an in-storage list but the list had been 
exhausted. 


20 Invalid parameters passed to the GETLINE service routine. 


24 A conditional GETMAIN was issued by GETLINE for input buffers and there was not 
sufficient space to satisfy the request. 


28 The terminal has been disconnected. 
32 An attempt to obtain a line from a command procedure DATA-ENDDATA group failed. 


40 A barrier element is on the top of the stack and SUBSTACK = YES was specified. No 
command buffer is passed back. 


PUTLINE - Putting a Line Out to the Terminal 


Use the PUTLINE macro instruction to prepare a line and write it to the 
terminal. Use PUTLINE to put out lines that do not require immediate response 
from the terminal; use PUTGET to put out lines that require immediate response. 
The types of lines which do not require response from the terminal are defined as 
data lines and informational message lines. 


The PUTLINE service routine prepares a line for output according to the 
operands you code into the list and execute forms of the PUTLINE macro 
instruction. The operands of the macro instruction indicate to the PUTLINE 
service routine the type of line being put out (data line or informational message 
line), the type of processing to be performed on the line (format only, second level 
informational message chaining, text insertion), and the TPUT options requested. 


This topic describes: 


The list and execute forms of the PUTLINE macro instruction 
The PUTLINE parameter block 

The types and formats of output lines 

PUTLINE message processing 

Return codes from PUTLINE 


Coding examples are included where appropriate. 
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The PUTLINE Macro Instruction - List Form 


The list form of the PUTLINE macro instruction builds and initializes a 
PUTLINE parameter block (PTPB), according to the operands you specify in the 
macro instruction. The PUTLINE parameter block indicates to the PUTLINE 
service routine which functions you want performed. Figure 12-17 shows the list 
form of the PUTLINE macro instruction; each of the operands is explained 
following the figure. Appendix A describes the notation used to define macro 
instructions. 


, SINGLE 
[symbol] | PUTLINE OUTPUT=(output address |,TERM ,MULTLVL ||, INFOR |) 
FORMAT] |,MULTLIN ||,DATA 


EDIT 


| Teneo ASIS wa | | uououo| : ROBREAK 


CONTROL] |,NOWAIT] |,HOLD BREAKIN 


»MF=L 


Figure 12-17. The List Form of the PUTLINE Macro Instruction 


OUTPUT = output address 
Indicates that an output line is to be written to the terminal. The type of 
line provided and the processing to be performed on that line by the 
PUTLINE service routine are described by the OUTPUT sublist operands 
TERM, FORMAT, SINGLE, MULTLVL, MULTLIN, INFOR and 
DATA. The default values are TERM, SINGLE, and INFOR. The output 
address differs depending upon whether the output line is an informational 
message or a data line. For DATA requests, it is the address of the 
beginning (the fullword header) of a data record to be written to the 
terminal. For informational message requests (INFOR), it is the address of 
the output line descriptor. The output line descriptor (OLD) describes the 
message to be put out, and contains the address of the beginning (the 
fullword header) of the message or messages to be written to the terminal by 
the PUTLINE service routine. 


When a barrier element is the top stack element, and PUTLINE 1s operating 
in the foreground, PUTLINE displays the output at the terminal; if 
PUTLINE is operating in the background, it places the output in the 
SYSTSOUT data set. 


TERM 
Write the line out to the terminal. 


FORMAT 
The output request is only to format a single message and not to put the 
message out to the terminal. The PUTLINE service routine returns the 
address of the formatted line by placing it in the third word of the 
PUTLINE parameter block. 


SINGLE 
The output line is a single line. 
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MULTLVL 
The output message consists of multiple levels. INFOR must be specified. 


MULTLIN . 
The output data consists of multiple lines. DATA must be specified. 


INFOR 


The output line is an informational message. 


DATA 


The output line is a data line. 


TERMPUT 
Specifies the TPUT options requested. PUTLINE issues a TPUT SVC to 
write the line to the terminal. This operand indicates which of the TPUT 
options you want to use. The TPUT options are EDIT, ASIS, or 
CONTROL; WAIT or NOWAIT; NOHOLD or HOLD; and NOBREAK 
or BREAKIN. The default values are EDIT, WAIT, NOHOLD, and 
NOBREAK. 


EDIT 


Specifies that in addition to minimal editing (see ASIS), the following TPUT 
functions are requested: 


l. 


ASIS 


Any trailing blanks are removed before the line is written to the 
terminal. If a blank line is sent, the terminal vertically spaces one line. 


Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 


All terminal control characters (for example: bypass, restore, horizontal 
tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 


Specifies that minimal editing is to be performed by TPUT as follows: 


1. 


The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program-caused I/O errors. This does not mean that all unprintable 
characters are eliminated. Restore, upper case, lower case, bypass, and 
bell ring, for example, might be valid but nonprinting characters at 
some terminals. (See CONTROL.) 


Transmission control characters are added. 


EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 


If you specify EDIT, NL is handled as described by item 3 under EDIT. 
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If the NL is embedded in your message, it is sent to the terminal as a 
carrier return. No idle characters are added (see item 6 below). This 
may Cause overprinting, particularly on terminals that require a line-feed 
character to position the carrier on a new line. 


4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, TPUT attempts alternate methods to accomplish the 
backspace. 


5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 


6. Idle characters are sent at the end of each line to prevent typing as the 
carrier returns. 


CONTROL 
Specifies that the output line is composed of terminal control characters and 
will not print or move the carrier on the terminal. This option should be 
used for transmission of characters such as bypass, restore, or bell ring. 


WAIT 
Specifies that control will not be returned until the output line has been 
placed into a terminal output buffer. 


NOWAIT 
Specifies that control should be returned whether or not a terminal output 
buffer is available. If no buffer is available, a return code of 8 (decimal) 
will be returned in register 15 to the command processor. 


NOHOLD 
Specifies that control is to be returned to the routine that issued the 
PUTLINE macro instruction, and that the routine can continue processing 
as soon as the output line has been placed on the output queue. 


HOLD 
Specifies that the routine that issued the PUTLINE macro instruction 
cannot continue its processing until this output line has been put out to the 
terminal or deleted. 


NOBREAK 
Specifies that if the terminal user has started to enter input, the user is not 
to be interrupted. The output message is placed on the output queue to be 
printed after the terminal user has completed the line. 


BREAKIN 
Specifies that output has precedence over input. If the user at the terminal 
is transmitting, he is interrupted, and this output line is sent. Any data that 
was received before the interruption is kept and displayed at the terminal 
following this output line. 
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MF=L 
Indicates that this is the list form of the macro instruction. 


Note: In the list form of the macro instruction, only 


PUTLINE MF=L 


is required. The output line address is required for each issuance of the 
PUTLINE macro instruction but it may be supplied in the execute form of the 
macro instruction. 


The other operands and sublists are optional because you can supply them in the 
execute form of the macro instruction, or they will be supplied by the macro 
expansion if you want the default values. 


The operands you specify in the list form of the PUTLINE macro instruction set 
up control information used by the PUTLINE service routine. This control 
information is passed to the PUTLINE service routine in the PUTLINE 
parameter block, a three-word parameter block built and initialized by the list 
form of the PUTLINE macro instruction. 


The PUTLINE Macro Instruction - Execute Form 


Use the execute form of the PUTLINE macro instruction to put a line or lines 
out to the terminal, to chain second level messages, and to format a line and 
return the address of the formatted line to the code that issued the PUTLINE 
macro instruction. The execute form of the PUTLINE macro instruction 
performs the following functions: 


1. It can be used to set up the input/output parameter list (OPL). 

2. It can be used to initialize those fields of the PUTLINE parameter block 
(PTPB) not initialized by the list form of the macro instruction, or to modify 
those fields already initialized. 


3. It passes control to the PUTLINE service routine. 


The PUTLINE service routine makes use of the IOPL and the PTPB to determine 
which of the PUTLINE functions you want performed. 
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Figure 12-18 shows the execute form of the PUTLINE macro instruction; each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


[symbol] | PUTLINE | [PARM=parameter address][,UPT=upt address) 
[,ECT=ect address][,ECB=ecb address] 
,OUTPUT=(output address] , TERM , SINGLE , LNFOR |) 
,MULTLVL ,DATA 


FORMAT 
,MULTLIN 


EDIT 
, TERMPUT=(] ASIS ,WAIT ,NOHOLD| |,NOBREAK| ) 
CONTROL| |,NOWAIT| |, HOLD , BREAKIN 
,ENTRY=|]entry address| | ,MF=(E|,list address| ) 
(15) (1) 


Figure 12-18. The Execute Form of the PUTLINE Macro Instruction 


PARM = parameter address 
Specifies the address of the 3-word PUTLINE parameter block (PTPB). It 
may be the address of a list form of the PUTLINE macro instruction. The 
address is any address in an RX instruction, or the number of one of the 
general registers 2-12 enclosed in parentheses. This address will be placed 
into the IOPL. 


UPT =upt address 
Specifies the address of the user profile table (UPT). You may obtain this 
address from the command processor parameter list (CPPL) pointed to by 
register 1 when a command processor is attached by the terminal monitor 
program. The address may be any address valid in an RX instruction or it 
may be placed in one of the general registers 2-12 and the register number 
enclosed in parentheses. This address will be placed into the IOPL. 


ECT =ect address 
Specifies the address of the environment control table (ECT). You may 
obtain this address from the CPPL pointed to by register 1 when a 
command processor is attached by the terminal monitor program. The 
address may be any address valid in an RX instruction or it may be placed 
in one of the general registers 2-12 and the register number enclosed in 
parentheses. This address will be placed into the IOPL. 


ECB = ecb address 
Specifies the address of the event control block (ECB). You must provide a 
one-word event control block and pass its address to the PUTLINE service 
routine. This address will be placed into the IOPL. The address may be 
any address valid in an RX instruction or it may be placed in one of the 
general registers 2-12 and the register number enclosed in parentheses. 


OUTPUT = output address 
Indicates that an output line is provided. The type of line provided and the 
processing to be performed on that line by the PUTLINE service routine are 
described by the OUTPUT sublist operands TERM, FORMAT, SINGLE 
MULTLVL, MULTLIN, INFOR and DATA. The default values are 
TERM, SINGLE, and INFOR. 
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The output address differs depending upon whether the output line is an 
informational message or a data line. For DATA requests, it is the address 
of the beginning (the fullword header) of a data record to be put out to the 
terminal. For informational message requests (INFOR), it is the address of 
the output line descriptor. The output line descriptor (OLD) describes the 
message to be put out, and contains the address of the beginning (the 
fullword header) of the message or messages to be written to the terminal by 
the PUTLINE service routine. 


When a barrier element is the top stack element, and PUTLINE is operating 
in the foreground, PUTLINE displays the output at the terminal; if 
PUTLINE is operating in the background, it places the output in the 
SYSTSOUT data set. 


TERM 
Write the line out to the terminal. 


FORMAT 
The output request is only to format a single message and not to put the 
messages out to the terminal. The PUTLINE service routine returns the 
address of the formatted line by placing it in the third word of the 
PUTLINE parameter block. 


SINGLE 
The output line is a single line. 


MULTLVL 
The output message consists of multiple levels. INFOR must be specified. 


MULTLIN 
The output data consists of multiple lines. DATA must be specified. 


INFOR 
The output line is an informational message. 


DATA 
The output line is a data line. 


TERMPUT 
Specifies the TPUT options requested. PUTLINE issues a TPUT SVC to 
write the line to the terminal. This operand indicates which of the TPUT 
options you want to use. The TPUT options are EDIT, ASIS, or 
CONTROL; WAIT or NOWAIT; NOHOLD or HOLD; and NOBREAK 
or BREAKIN. The default values are EDIT, WAIT, NOHOLD, and 
NOBREAK. 


EDIT 
Specifies that in addition to minimal editing (see ASIS), the following TPUT 


functions are requested: 


1. Any trailing blanks are removed before the line is written to the 
terminal. Ifa blank line is sent, the terminal vertically spaces one line. 


2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 
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3. All terminal control characters (for example: bypass, restore, horizontal 
tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 


ASIS 
Specifies that minimal editing is to be performed by TPUT as follows: 


1. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program-caused I/O errors. This does not mean that all unprintable 
characters are eliminated. Restore, upper case, lower case, bypass, and 
bell ring, for example, may be valid but nonprinting characters at some 
terminals. (See CONTROL.) 


2. Transmission control characters are added. 


3. EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 


If you specify EDIT, NL is handled as described in 3 under EDIT. 


If the NL is embedded in your message, a semicolon is substituted for 
NL and sent to the terminal. No idle characters are added (see item 6 
below). This may cause overprinting, particularly on terminals that 
require a line-feed character to position the cursor on a new line. 


4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, the PUTLINE service routine attempts alternate methods 
to accomplish the backspace. 


5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 


6. Idle characters are sent at the end of each line to prevent typing as the 
carrier returns. 


CONTROL 
Specifies that the output line is composed of terminal control characters and 
will not display or move the cursor on the terminal. This option should be 
used for transmission of characters such as bypass, restore, or bell ring. 


WAIT 
Specifies that control will not be returned until the output line has been 
placed into a terminal output buffer. 


NOWAIT 
Specifies that control should be returned whether or not a terminal output 
buffer is available. If no buffer is available, a return code of 8 is returned in 
register 15. 


12-42 TSO/E Guide to Writing a TMP or a CP 


J 


J 


NOHOLD 
Specifies that control is returned to the routine that issued the PUTLINE 
macro instruction, and it can continue processing, as soon as the output line 
has been placed on the output queue. 


HOLD 
Specifies that the module that issued the PUTLINE macro instruction is not 
to resume processing until the output line has been put out to the terminal 
or deleted. 


NOBREAK 
Specifies that if the terminal user has started to enter input, the user is not 
to be interrupted. The output message is placed on the output queue to be 
displayed after the terminal user has completed the line. 


BREAKIN 
Specifies that output has precedence over input. If the user at the terminal 
is transmitting, the user is interrupted, and the output line is sent. Any data 
that was received before the interruption is kept and displayed at the 
terminal following the output line. 


ENTRY entry address or (15) 
Specifies the entry point of the PUTLINE service routine. If ENTRY is 
omitted, the PUTLINE macro expansion will generate a LINK macro 
instruction to invoke the PUTLINE service routine. The address may be 
any address valid in an RX instruction or (15) if the entry point address has 
been loaded into general register 15. 


MF=E 
Indicates that this is the execute form of the PUTLINE macro instruction. 


list address 

(1) 
The address of the four-word input/output parameter list (IOPL). This may 
be a completed IOPL that you have built, or 4 words of declared storage to 
be filled from the PARM, UPT, ECT, and ECB operands of this execute 
form of the PUTLINE macro instruction. The address is any address valid 
in an RX instruction or (1) if the parameter list address has been loaded 
into general register 1. 


Note: In the execute form of the PUTLINE macro instruction only the following 
is required: 


PUTLINE MF=(E, 


The PARM, UPT, ECT, and ECB operands are not required if you have built 
your IOPL in your own code. 


) 


list address 
(1) 


The output line address is required for each issuance of the PUTLINE macro 
instruction, but you may supply it in the list form of the macro instruction. 
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The other operands and sublists are optional because you may have supplied them 

in the list form of the macro instruction or in a previous execute form, or because 

you may want to use the default values which are automatically supplied by the J 
macro expansion itself. 


The ENTRY operand need not be coded in the macro instruction. If it is not, a 
LINK macro instruction will be generated by the macro expansion to invoke the 
I/O service routine. 


The operands you specify in the execute form of the PUTLINE macro instruction 
set up control information used by the PUTLINE service routine. You can use 
the PARM, UPT, ECT, and ECB operands of the PUTLINE macro instruction 
to build, complete or modify an IOPL. The OUTPUT and TERMPUT operands 
and their sublist operands initialize the PUTLINE parameter block. The 
PUTLINE parameter block is referenced by the PUTLINE service routine to 
determine which functions you want PUTLINE to perform. 


Building the PUTLINE Parameter Block 


When the list form of the PUTLINE macro instruction expands, it builds a 

three-word PUTLINE parameter block (PTPB). The list form of the macro 

instruction initializes the PTPB according to the operands you have coded in the 

macro instruction. The initialized block, which you may later modify with the 

execute form of the PUTLINE macro instruction, indicates to the PUTLINE 

service routine the function you want performed. You must supply the address of 

the PTPB to the execute form of the PUTLINE macro instruction. Since the list 

form of the macro instruction expands into a PTPB, all you need do is pass the 

address of the list form of the macro instruction to the execute form as the ’ 
PARM value. J 
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The PUTLINE parameter block is defined by the IKJPTPB DSECT. 
Figure 12-19 describes the contents of the PTPB. 


Number 
of Bytes Contents or Meaning 


Control flags. These bits describe the output line to the PUTLINE 
service routine. 


The output line is a message. 

The output line is a data line. 

The output line is a single level or a single line. 

The output is multiline. 

The output is multilevel. 

“gee. wel The output line is an informational message. 
ties Reserved bits. 


The format only function was requested. 
Reserved bits. 


TPUT options field. These bits indicate to the TPUT SVC which of 
the TPUT options you want to use. 


XX.X XXXX 


Byte | 
0 


Always set to 0 for TPUT. 


WAIT processing has been requested. Control will be returned to the 
issuer of PUTLINE only after the output line has been placed into a 
terminal output buffer. 


NOWAIT processing has been requested. Control will be returned to 
the issuer of PUTLINE whether or not a terminal output buffer is 
available. 


NOHOLD processing has been requested. The command processor 
that issued the PUTLINE can resume processing as soon as the output 
line has been placed on the output queue. 


HOLD processing has been requested. The command processor that 
issued the PUTLINE is not to resume processing until the output line 
has been written to the terminal or deleted. 


NOBREAK processing has been requested. The output line will be 
printed only when the terminal user is not entering a line. 


BREAKIN processing has been requested. The output line is to be 
sent to the terminal immediately. If the terminal user is entering a line, 
he is to be interrupted. 


EDIT processing has been requested. 
ASIS processing has been requested. 
CONTROL processing has been requested. 
a! has Reserved. 
Reserved. 


PTPBOPUT The address of the output line descriptor (OLD) if the output line is a 
message. The address of the fullword header preceding the data if the 
output line is a single data line. The address of a forward-chain 
pointer preceding the fullword data header, if the output is multiline 


data. 


PTPBFLN Address of the format only line. The PUTLINE service routine places 


the address of the formatted line into this field. 


Figure 12-19. The PUTLINE Parameter Block 
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Types and Formats of Output Lines 


There are two types of output lines processed by the PUTLINE service routine: 


Data lines (DATA) 
Message lines (INFOR) 


The OUTPUT sublist operands you specify in the PUTLINE macro instruction 
indicate to the PUTLINE service routine which type of line you want processed 
(DATA, INFOR), whether the output consists of one line, several lines, or several 
levels of messages (SINGLE, MULTLIN, MULTLVL), and whether the line is to 
be written to the terminal (TERM), or formatted only (FORMAT). 


1. 


Data Lines: A data line is the simplest type of output processed by the 
PUTLINE service routine. It is simply a line of text to be written to the 
terminal. PUTLINE does not format the line or process it in any way; it 
merely writes the line, as it appears, out to the terminal. There are two kinds 
of data lines, single line data and multiline data; each is handled differently 
by the PUTLINE service routine. 


Single Line Data: Single line data is one contiguous character string that 
PUTLINE places out to the terminal as one logical line. If the line of data 
you provide exceeds the terminal line length, the TPUT routine segments the 
line and puts it out as several terminal lines. PUTLINE accepts single line 
data in the format shown in Figure 12-20. 


PUTLINE OUTPUT = (output address, =, SINGLE, DATA) | 


Figure 12-20. PUTLINE Single Line Data Format 


You must precede your line of data with a 4-byte header field. The first two 
bytes contain the length of the output line, including the header; the second 
two bytes are reserved for offsets and are set to zero for data lines. You pass 
the address of the output line to the PUTLINE service routine by coding the 
beginning address of the four-byte header as the OUTPUT operand address 
in either the list or the execute form of the macro instruction. When the 
macro instruction expands, it places this data line address into the second 
word of the PUTLINE parameter block. 
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Figure 12-21 is an example of the code that could be used to write a single 
line of data to the terminal using the PUTLINE macro instruction. Note that 
the execute form of the PUTLINE macro instruction is used in this example 
to construct the input/output parameter list, and that the TERMPUT 
operands are not coded in either the list or the execute form of the macro 


instruction; the default values will be assumed by the PUTLINE service 
routine. 
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Multiline Data: Multiline data is a chain of single lines. Each line of data is 
processed by the PUTLINE service routine exactly as if it were single line 
data. Each element of the chain, however, begins a new line to the terminal. 
By specifying multiline data (MULTLIN) in the PUTLINE macro 
instruction, you can put out several variable length, non-contiguous lines at 
the terminal with one execution of the macro instruction. PUTLINE accepts 
multiline data in a format similar to that of single line data except that each 
line is prefaced with a fullword forward chain pointer. Figure 12-22 shows 
the format of PUTLINE multiline data. 


PUTLINE OUTPUT = (output address, , MULTLIN, DATA) ~~ 


— 


Length 


[Racrwagemn | ees [om [om fd 


Figure 12-22. PUTLINE Multiline Data Format 


Each of the forward-chain pointers points to the next data line to be written 
to the terminal. The forward-chain pointer in the last data line contains 
zeros. In the case of multiline data, you pass the address of the output line to 
the PUTLINE service routine by coding the beginning address of the first 
forward-chain pointer as the OUTPUT operand address in either the list or 
the execute form of the macro instruction. When the macro instruction 
expands, it will place this multiline data address into the second word of the 
PUTLINE parameter block. 
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Figure 12-23 is an example of the code required to write multiple lines of 
data to the terminal using the PUTLINE macro instruction. Note that the 
programmer has built his own IOPL rather than build it with the execute 
form of the PUTLINE macro instruction. Note also the use of the IOPL and 
CPPL DSECTs (generated by the IKJIOPL and IKJCPPL macro 
instructions). These provide an easy method of accessing the fields within the 
IOPL and the CPPL, and they protect your code from changes made to the 
control blocks. 
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Figure 12-23 (Part 1 of 2). Coding Example - PUTLINE Multiline Data 
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Figure 12-23 (Part 2 of 2). Coding Example - PUTLINE Multiline Data 
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2. Message Lines: If you code INFOR in the PUTLINE macro instruction, the 
PUTLINE service routine writes the information you supply as an 
informational message and provides additional functions not applicable to 
data lines. An informational message is a line of output from the program in 
control to the user at the terminal. It is used solely to pass output to the 
terminal; no input from the terminal is required after an informational 
message. 


There are two types of informational messages processed by the PUTLINE 
service routine: 


e Single level messages (SINGLE) 
e Multilevel message (MULTLVL) 


Single Level Messages: A single level message is composed of one or more 
message segments to be formatted and written to the terminal with one 
execution of the PUTLINE macro instruction. 


Multilevel Messages: Multilevel messages are composed of one or more 
message segments to be formatted and written to the terminal, and one or 
more message segments to be formatted and placed on an internal chain in 
shared subpool 78. This internal chain can either be put out to the terminal 
or purged by a second execution of the PUTLINE macro instruction. 


12-50 TSO/E Guide to Writing a TMP or a CP 


J 


Passing the Message Lines to PUTLINE 


C You must build each of the message segments to be processed by the PUTLINE 
service routine as if it were a line of single line data. The segment must be 
preceded by a four-byte header field -- the first two bytes containing the length of 
the segment, including the header, and the second two bytes containing zeros or 
an offset value if you use the text insertion facility. See “Using the PUTLINE 
Text Insertion Function” for a discussion of offset values. This message line 
format is required whether the message is a single level message or a multilevel 
message. 


Because of the additional operations performed on message lines, however, you 
must provide the PUTLINE service routine with a description of the line or lines 
that are to be processed. This is done with an output line descriptor (OLD). 


There are two types of output line descriptors, depending on whether the messages 
are single level or multilevel. 


The OLD required for a single level message is a variable-length control block 
which begins with a fullword value representing the number of segments in the 
message, followed by fullword pointers to each of the segments. 


The format of the OLD for multilevel messages varies from that required for 
single level messages in only one respect. You must preface the OLD with a 
fullword forward-chain pointer. This chain pointer points to another output line 
descriptor or contains zero to indicate that it is the last OLD on the chain. 
Figure 12-24 shows the format of the output line descriptor. 


YW Number 
of = Contents or Meaning 


The address of the next OLD, or zero if this is the last one on the chain. 
This field is present only if the message pointed to is a multilevel 
message. 


The number of message segments pointed to by this OLD. 
The address of the first message segment. 


The address of the next message segment. 


Figure 12-24. The Output Line Descriptor (OLD) 


You must build the output line descriptor and pass its address to the PUTLINE 
service routine as the OUTPUT operand address in either the list or the execute 
form of the macro instruction. When the macro instruction expands, it places the 
address of the output line descriptor into the second word of the PUTLINE 
parameter block. 
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Figure 12-25. Control Block Structures for PUTLINE Messages 
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PUTLINE Message Line Processing 


é In addition to writing a message out to the terminal, the PUTLINE service 
routine provides the following additional functions for message line (INFOR) 
processing: 


Message identification stripping 
Text insertion 

Formatting only 

Second level informational chaining 


Figure 12-26 shows the distribution of these PUTLINE service routine functions 
over the two output message types. 


Message Types 
Single Level Multilevel 


Message ID Stripping 


Formatting Only 
Second Level Informational Chaining 


Figure 12-26. PUTLINE Functions and Message Types 


Stripping Message Identifiers: The user indicates whether or not he wants 
message identifiers displayed at the terminal. The use does this with the 
PROFILE command. (See TSO/E Command Language Reference and TSO/E 
User's Guide.) If the terminal user indicates no message identifiers are to be 
, displayed, the PUTLINE service routine strips them off the message before 
Cc writing the message to the terminal. 


A message identifier must be a variable-length character string, containing no 
leading or embedded blanks, must not exceed a maximum length of 255 
characters, and must be terminated by a blank. 


Messages without message identifiers must begin with a blank. A message 
beginning with a blank is handled by the PUTLINE service routine as a message 
that does not require message identifier stripping, regardless of what the user at 
the terminal has requested. If you do not provide a message identifier, and do 
not begin your message with a blank, the beginning of your message up to the 
first blank will be stripped off by the PUTLINE service routine if message 
identifier stripping is requested from the terminal. If the message segment does 
not contain at least one blank, PUTLINE will return a code of 12 (invalid 
parameters) in register 15, even if message ID stripping is not requested from the 
terminal. 


The following examples show the effects of the PUTLINE message identifier 
stripping function. 


If you provide message identifiers on your messages and the terminal user does 
not request message ID stripping, your message will appear at the terminal exactly 
as it appears here: 


MESSAGEOO10 THIS IS A MESSAGE. 
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If the user at the terminal requests message ID stripping, the message will appear 
as: 


THIS IS A MESSAGE. J 


If you do not want to use message identifiers on your output messages, begin your 
message with a blank. A message beginning with a blank is unaffected by a 
terminal user’s request for message ID stripping and will appear as you wrote it, 
minus the blank. 


Using the PUTLINE Text Insertion Function: The text insertion function of the 
PUTLINE service routine allows you to build or modify messages at the time you 
put them out to the terminal. With text insertion you can respond to different 
output message requirements with one basic message (the primary segment). You 
Can insert text into this primary segment or add text to it, and thereby build an 
output message to meet the current processing situation. 


To use text insertion you pass your messages to the PUTLINE service routine as 

a variable number of text segments -- from 1 to 255 segments are permissible. 
Each segment may contain from 0 to 255 characters, however, the total number of 
characters in all the segments must not exceed 256. You must precede each of 
these text segments with a four-byte header: the first two bytes containing the 
length of the message, including the header, and the second two bytes containing 
an offset value. The offset value in the primary segment must be zero. The offset 
in any secondary segments may be from zero to the length of the primary 
segment’s text field. An offset of zero in a secondary segment implies that the 
segment is to be placed before the primary segment. An offset that is equal to the 
length of the primary segment’s text field implies that the secondary segment is to 
be placed after the primary segment. An offset of n, where n represents a value J 
greater than zero but less than the total length of the primary segment, implies 
that the segment is to be inserted after the nth byte of the primary segment. 
PUTLINE places the secondary segment after that character, completes the 
message, and puts it out to the terminal. 


If you specify an offset in a secondary segment, greater than the length of the 
primary segment, PUTLINE cannot handle the request and returns an error code 
of 12 (invalid parameters) in register 15. If the secondary segments do not appear 
in the OLD with their offsets in ascending order, PUTLINE returns an error code 
of 12 (invalid parameters) in register 15. 


If you provide more than one secondary segment to be inserted into a primary 
segment, the offset fields on each of the secondary segments must indicate the 
position within the original primary segment at which you want them to appear. 
PUTLINE determines the points of insertion by counting the characters of the 
original primary segment only. As an example, if you provided one primary and 
two secondary segments as shown: 


2 bytes 2 bytes 28 bytes 


a as PLEASE ENTER TO PROCESSING 
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Figure 12-27 (Part 1 of 2). 


PUTLINE would place the first insert, TEXT, after the 13th character, and the 
second insert, CONTINUE, after the 17th character of the text field of the 
primary segment. After PUTLINE inserts the two text segments, the message 
would read: 


PLEASE ENTER TEXT TO CONTINUE PROCESSING 


The leading and trailing blanks are automatically stripped off before the message 
is written to the terminal. 


Figure 12-27 is an example of the code required to make use of the text insertion 
feature of the PUTLINE service routine; it uses the text segments shown above. 


Note that the operand INFOR, which indicates to the PUTLINE service routine 
that the text segments are to be processed as informational messages, requires an 
output line descriptor to point to the message segments. Only one output line 
descriptor (QNEOLD) is required to point to the 3 message segments because the 
3 segments are to be combined into one single level message. 
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Coding Example - PUTLINE Text Insertion 
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Figure 12-27 (Part 2 of 2). 
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Coding Example - PUTLINE Text Insertion 


Using the Format Only Function: You can also use the PUTLINE service routine 
to format a message but not write it at the terminal. To do this, code the 
FORMAT operand in the PUTLINE macro instruction and pass PUTLINE the 
same message segment structure required for the text insertion function. The 
PUTLINE service routine performs text insertion if requested and places the 
finished message in subpool 1, which is not shared. It then places the address of 
the formatted line into the third word of the PUTLINE parameter block. The 
storage occupied by the formatted message belongs to your program and, if space 
is a consideration, must be freed by it. The returned formatted line is in the 
variable-length record format; that is, it is preceded by a four-byte header. You 
can use the first two bytes of this header to determine the length of the returned 
message, and later, to free the real storage occupied by the message with the R 
form of the FREEMAIN macro instruction. 


One difference between format only processing and text insertion processing is 
that format only processing can be used only on single level messages. You 
cannot use the format only feature to format multilevel messages. You can 
however, use the second level informational chaining function of PUTLINE to 
format second level messages and place them on an internal chain. 
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Building a Second Level Informational Chain: PUTLINE can accept two levels of 
informational messages at each execution of the service routine. It formats the 
first level message and puts it out to the terminal. The second level message is 
formatted and a copy of it is placed on an internal chain in shared subpool 78. 
This internal chain, the second level informational chain, is maintained by the I/O 
service routines for the duration of one command or subcommand processor. 
You can use the PUTLINE service routine to purge this chain or to put it out to 
the terminal in its entirety. 


To purge the chain without putting it out to the terminal, you must turn on the 
high order bit in the first byte (ECTMSGF) of the third word of the environment 
control table (ECT). The ECT is pointed to by the second word of the 
input/output parameter list, and may be mapped by the IKJECT DSECT. The 
next time any chaining or unchaining is requested with PUTLINE or PUTGET, 
the second level informational chain will be eliminated. 


To put the entire chain out to the terminal, use the PUTLINE macro instruction 
and place a zero address where the output line address is normally required. This 
will cause the PUTLINE service routine to write the chain to the terminal and 
eliminate the internal chain. You will normally use this procedure only if your 
attention exit routine is using the PUTLINE macro instruction to process a 
question mark entered from the terminal. 


Figure 12-28 is an example of the code required to build a second level 
informational chain. It executes the PUTLINE service routine by using two 
different execute form macro instructions to modify the PUTLINE parameter 
block built by the list form of the PUTLINE macro instruction. 


The code shown puts two messages out to the terminal and places two second 
level messages on an internal chain. It then executes a third execute form of the 
PUTLINE macro instruction with a zero OUTPUT address to put the second 
level chain out to the terminal. 


Note that the offset value for the primary message segment must always be zero, 
and when placing second level messages on an internal chain, the offset value for 
the second level message must also be zero. Note also that you do not place a 
message identifier on a second level message. 
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Return Codes from PUTLINE 


When the PUTLINE service routine returns control to the program that invoked ) 
it, it provides one of the following return codes in general register 15: 


Code Meaning 


decimal 

0 PUTLINE completed normally. 

4 The PUTLINE service routine did not complete. An attention interruption occurred during 
its execution, and the attention handler turned on the completion bit in the communications 
ECB. 

8 The NOWAIT option was specified and the line was not written to the terminal. 

12 Invalid parameters were supplied to the PUTLINE service routine. 

16 A conditional GETMAIN was issued by PUTLINE for output buffers and there was not 


sufficient real storage to satisfy the request. 


20 The terminal has been disconnected. 


Note: The GNRLFAIL service routine described in this book can be invoked to 
issue a meaningful error message for a PUTLINE error code. 


PUTGET - Putting a Message Out to the Terminal and Obtaining a Line of Input in 
Response 


Use the PUTGET macro instruction to put messages out to the terminal and to J 
obtain a response to those messages. A message to the user at the terminal which 
requires a response is called a conversational message. There are two types of 

conversational messages: 


@ Mode messages - Those which tell the user at the terminal which processing 
mode he is in so that he can enter a response applicable to that processing 
mode. Examples of mode messages are the READY message sent to the 
terminal by the terminal monitor program to indicate that it expects a 
command to be entered, and the command name (EDIT, TEST, etc.) sent by 
a command processor to indicate that it is ready to accept a subcommand 
name. 


® Prompt messages - Those which prompt the user at the terminal to enter 
parameters required by the program in control, or to reenter those parameters 
which were previously entered incorrectly. Prompt information can only be 
obtained from the user at the terminal. 


The input line returned by the PUTGET service routine can come from the 
terminal or from an in-storage list; PUTGET determines the source of input from 
the top element of the input stack unless you have specified the TERM or ATTN 
operands in the PUTGET macro instruction. 


PUTGET, like PUTLINE and GETLINE, has many parameters. The parameters 


are passed to the PUTGET service routine according to the operands you code in 
the list and the execute forms of the PUTGET macro instruction. ) 
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This topic describes: 


The list and execute forms of the PUTGET macro instruction 
Building the PUTGET parameter block 

Types and formats of the output line 

Passing the message lines to PUTGET 

PUTGET processing 

Input line format - the input buffer 

An example of PUTGET 

Return codes from PUTGET 


The PUTGET Macro Instruction - List Form 


The list form of the PUTGET macro instruction builds and initializes a PUTGET 
parameter block (PGPB), according to the operands you specify in the PUTGET 
macro instruction. The PUTGET parameter block indicates to the PUTGET 
service routine which of the PUTGET functions you want performed. 

Figure 12-29 shows the list form of the PUTGET macro instruction; each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


, PROMPT 
[symbol] PUTGET OUTPUT=(output address |,SINGLE 
,MULTLVL 
EDIT 
, TERMPUT=(4 ASIS ,WAIT , NOHOLD ,NOBREAK ) 
CONTROL| |,NOWAIT| |,HOLD , BREAKIN 
, TERMGET=(| EDIT| |,WAIT )|} ,MF=L 
ASIS| |,NOWAIT 
, SUBSTACK=(|]NO |) 
YES 


Figure 12-29. The List Form of the PUTGET Macro Instruction 


OUTPUT = output address 
Specify the address of the output line descriptor or a zero. The output line 
descriptor (OLD) describes the message to be put out, and contains the 
‘address of the beginning (the one-word header) of the message or messages 
to be written to the terminal. You have the option under MODE 
processing to provide or not provide an output message. If you do not 
provide an output line, code OUTPUT =0, and only the GET functions will 
take place. If you do provide an output message, the type of message and 
the processing to be performed by the PUTGET service routine are 
described by the OUTPUT sublist operands SINGLE, MULTLVL, 
PROMPT, MODE, PTBYPS, TERM, and ATTN. SINGLE and 
PROMPT are the default values. 


SINGLE 
The output message is a single level message. 
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MULTLVL 
The output message consists of multiple levels. The first level message is 
written to the terminal, the second level messages are printed at the J 
terminal, one at a time, in response to question marks entered from the 
terminal. PROMPT must also be specified or defaulted to. 


PROMPT 
The output line is a prompt message. 


MODE 
The output line is a mode message. 


PTBYPS 
The output line is a prompt message and the terminal user’s response will 
not be displayed at those terminals that support the print inhibit feature. A 
terminal user can override bypass processing by pressing an attention 
followed by pressing the ENTER key before entering input. 


TERM 
Specifies that the output line (a mode message) is to be written to the 
terminal, and a line is to be returned from the terminal, regardless of the 
top element of the input stack. 


ATTN 
Specifies that the output line (a mode message) is to be initially suppressed 
but an input line is to be returned from the terminal. 


TERMPUT = J 
Specifies the TPUT options requested. Since PUTGET issues a TPUT SVC 
to write the message to the terminal, this operand is used to indicate which 
of the TPUT options you want to use. The TPUT options are EDIT, ASIS 
or CONTROL; WAIT, or NOWAIT; NOHOLD, or HOLD; and 
NOBREAK or BREAKIN. The default values are EDIT, WAIT, 
NOHOLD, and NOBREAK. 


EDIT 
Specifies that in addition to minimal editing (see ASIS), the following TPUT 
functions are requested: 


1. Any trailing blanks are removed before the line is written to the 
terminal. If a blank line is sent, the terminal vertically spaces one line. 


2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 


3. All terminal control characters (for example: bypass, restore, horizontal 


tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 
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ASIS 
Specifies that minimal editing is to be performed by TPUT as follows: 


1. The line of output is to be translated from EBCDIC to terminal code. 
Invalid characters will be converted to printable characters to prevent 
program caused I/O errors. This does not mean that all unprintable 
characters will be eliminated. Restore, upper case, lower case, bypass, 
and bell ring, for example, might be valid but nonprinting characters at 
some terminals. (See CONTROL.) 


2. Transmission control characters will be added. 


3. EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 


If you specify EDIT, NL is handled as described in item 3 under EDIT. 


If the NL is embedded in your message, it is sent to the terminal as a 
cursor return. No idle characters are added (see item 6 below). This 
may cause overprinting, particularly on terminals that require a line-feed 
character to position the cursor on a new line. 


4. If you have used backspace in your output message but the backspace 
character does not exist on the terminal type to which the message is 
being routed, TPUT attempts alternate methods to accomplish the 
backspace. 


5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 


6. Idle characters are sent at the end of each line to prevent typing as the 
carrier returns. 


No line continuation checking is done. 


CONTROL 
Specifies that the output line is composed of terminal control characters and 
will not display or move the cursor on the terminal. This option should be 
used for transmission of characters such as bypass, restore, or bell ring. See 
ASIS for additional information. 


WAIT 
Specifies that control will not be returned to the program that issued the 
PUTGET until the output line has been placed into a terminal output 
buffer. 


NOWAIT 
Specifies that control should be returned to the program that issued the 
PUTGET macro instruction, whether or not a terminal output buffer is 
available. If no buffer is available a return code of 16 (decimal) is returned. 
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NOHOLD 
Specifies that control is to be returned to the issuer of the PUTGET macro 
instruction, and that program can resume processing as soon as the output 
line has been placed on the output queue. 


HOLD 
Specifies that the program that issued the PUTGET macro instruction 
cannot continue its processing until this output line has been put out to the 
terminal or deleted. 


NOBREAK 
Specifies that if the terminal user has started to enter input, he is not to be 
interrupted. The output message is placed on the output queue to be 
displayed after the terminal user has completed the line. 


BREAKIN 
Specifies that output has precedence over input. If the user at the terminal 
is transmitting, he is interrupted, and this output line is sent. Any data that 
was received before the interruption is kept and displayed at the terminal 
following this output line. 


TERMGET = 
Specifies the TGET options requested. Since PUTGET issues a TGET SVC 
to bring in a line of data, this operand is used to indicate to the TGET SVC 
which of the TGET options you wish to use. The TGET options are EDIT 
or ASIS, and WAIT or NOWAIT. The default values are EDIT and 
WAIT. 


EDIT 
Specifies that in addition to minimal editing (see ASIS), the buffer is to be 
filled out with trailing blanks. 


ASIS 
Specifies that minimal editing is to be done as follows: 


1. Transmission control characters are removed. 

2. The line of input is translated from terminal code to EBCDIC. 
3. Line deletion and character deletion editing is performed. 

4. Line feed and cursor return characters, if present, are removed. 


No line continuation checking is done. 


WAIT 
Specifies that control is to be returned to the program that issued the 
PUTGET macro instruction, only after an input message has been read. 


NOWAIT 
Specifies that control should be returned to the program that issued the 
PUTGET macro instruction whether or not a line of input is available. Ifa 
line of input is not available, a return code of 20 (decimal) is returned in 
register 15 to the command processor. 
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MF=L 
Indicates that this is the list form of the macro instruction. 


SUBSTACK 
For CLIST processing, YES indicates that normal stack operations continue 
until PUTGET reaches a barrier element. PUTGET then passes the caller a 
return code indicating that CLIST processing completed. The barrier 
element remains on the stack until the caller explicitly deletes it. NO is the 
default value and indicates that the barrier feature is not used. 


Note: If the caller issues PUTGET without SUBSTACK = YES, and a 
barrier element exists on the input stack, normal stack operations continue 
until PUTGET reaches a barrier element. In foreground mode, PUTGET 
then treats the barrier element as a terminal element. In background mode, 
PUTGET passes an end-of-data return code to the caller. Processing 
continues in this manner until the caller explicitly deletes the barrier 
element. 


Note: In the list form of the PUTGET macro instruction, only 


PUTGET MF=L 


is required. 


The output line address is not specifically required in the list form of the 
PUTGET macro instruction, but must be coded in either the list or the execute 
form. 


The other operands and their sublists are optional because you can supply them in 
the execute form of the macro instruction, or if you want the default values, they 
are supplied automatically by the expansion of the macro instruction. 


The operands you specify in the list form of the PUTGET macro instruction set 
up control information used by the PUTGET service routine. This control 
information is passed to the PUTGET service routine in the PUTGET parameter 
block, a four-word parameter block built and initialized by the list form of the 
PUTGET macro instruction. 


The PUTGET Macro Instruction - Execute Form 


Use the execute form of the PUTGET macro instruction to prepare a mode or a 
prompt message for output to the terminal, to determine whether or not that 
message should be sent to the terminal, and to return a line of input from the 
source indicated by the top element of the input stack to the program that issued 
the PUTGET macro instruction. 


You can use the execute form of the PUTGET macro instruction to build and 
initialize the input/output parameter list required by the PUTGET service routine, 
and to request PUTGET functions not already requested by the list form of the 
macro instruction, or to change those functions previously requested in either a 
list form or a previous execute form of the PUTGET macro instruction. 
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Figure 12-30 shows the execute form of the PUTGET macro instruction; each of 
the operands is explained following the figure. Appendix A describes the notation : 
used to define macro instructions. J 


[symbol] PUTGET [PARM=parameter address][,UPT=upt address) 
,ECT=ect address][,ECB=ecb address] 


, PROMPT 
,OUTPUT=(output address |,SINGLE ,MODE 
»MULTLVL |¢,PTBYPS 


id 


, ATTN 


, TERMPUT=(] ASIS ,WAIT ,NOHOLD | |, NOBREAK |) 
CONTROL | |,NOWAIT | |, HOLD , BREAKIN 


, TERMGET=(| EDIT | |, WAIT ) 
ASIS | |, NOWAIT 


,ENTRY= lentry address cain aad address |) 


(15) (1) 


, SUBSTACK=(| NO | ) 
YES 


_ 
| 
| 
| 
| 


Figure 12-30. The Execute Form of the PUTGET Macro Instruction 


PARM = parameter address 
Specifies the address of the four-word PUTGET parameter block (PGPB). 
This address 1s placed into the input/output parameter list IOPL). It may 
be the address of a list form PUTGET macro instruction. The address is J 
any address valid in an RX instruction, or you can put it in one of the 
general registers 2-12, and use that register number, enclosed in parentheses, 
as the parameter address. 


UPT = upt address 
Specifies the address of the user profile table (UPT). This address is placed 
into the IOPL when the execute form of the PUTGET macro instruction 
expands. You can obtain this address from the command processor 
parameter list (CPPL) pointed to by register 1 when the command processor 
is attached by the terminal monitor program. The address can be used as 
received in the CPPL or you can put it in one of the general registers 2-12, 
and use that register number, enclosed in parentheses, as the UPT address. 


ECT = ect address 
Specifies the address of the environment control table (ECT). This address 
is placed into the IOPL when the execute form of the PUTGET macro 
instruction expands. You can obtain this address from the command 
processor parameter list (CPPL) pointed to by register one when the 
command processor is attached by the terminal monitor program. The 
address can be used as received in the CPPL or you can put it in one of the 
general registers 2-12, and use that register number, enclosed in parentheses, 
as the ECT address. 
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ECB =ecb address 
Specifies the address of the command processor event control block (ECB). 
This address is placed into the JOPL by the execute form of the PUTGET 
macro instruction when it expands. 


You must provide a one-word event control block and pass its address to 
the PUTGET service routine by placing the address into the IOPL. If you 
code the address of the ECB in the execute form of the PUTGET macro 
instruction, the macro instruction places the address into the IOPL for you. 
The address can be any address valid in an RX instruction, or you can put 
it in one of the general registers 2-12, and use that register number, enclosed 
in parentheses, as the ECB address. 


If an attention interruption occurs while a mainline routine’s PUTGET 
macro is prompting for input (a READY message appears to the user), the 
region control task (RCT) passes control to an attention routine. The 
attention routine issues a PUTGET to prompt the user for the next 
command to be processed (a READY message appears to the user). If the 
user enters a null line, the attention routine does not post the attention 
ECB. The mainline PUTGET macro regains control, sees that the attention 
ECB is not posted, and redrives its TGET as if the attention interruption 
did not occur. If the user enters a command, the attention routine posts the 
attention ECB. When the mainline PUTGET macro regains control, it sees 
that the attention ECB is posted, sets the return code to 8, and returns to 
the mainline routine where the new command entered through the attention 
exit is processed. Note that if the ECB for which the mainline PUTGET 
macro checks (specified by the ECB= field of the PUTGET macro) is not 
equal to the ECB posted by the attention routine, the new command 
provided by the user is not processed. 


OUTPUT = output address 
Specifies the address of the output line descriptor or a zero. The output line 
descriptor (OLD) describes the message to be put out, and contains the 
address of the beginning (the one-word header) of the message or messages 
to be written to the terminal. You have the option under MODE 
processing to provide or not provide an output message. If you do not 
provide an output line, code OUTPUT =0, and only the GET function will 
take place. If you do provide an output message, the type of message and 
the processing to be performed by the PUTGET service routine are 
described by the OUTPUT sublist operands SINGLE, MULTLVL, 
PROMPT, MODE, PTBYPS, TERM, and ATTN. The default values are 
SINGLE and PROMPT. 


SINGLE 
The output message is a single level message. 


MULTLVL 
The output message consists of multiple levels. The first level message is 
written to the terminal, the second level messages are displayed at the 
terminal, one at a time, in response to question marks entered from the 
terminal. PROMPT must also be specified or defaulted to. 


PROMPT 
The output line is a prompt message. 
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MODE 
The output line is a mode message. 


PTBYPS 
The output line is a prompt message and the terminal user’s response will 
not display at those terminals that support the print inhibit feature. A 
terminal user can override bypass processing by pressing an attention 
followed by pressing the ENTER key before entering input. 


TERM 
Specifies that the output line (a mode message) is to be written to the 
terminal, and a line is to be returned from the terminal, regardless of the 
top element of the input stack. 


ATTN 
Specifies that the output line (a mode message) is to be initially suppressed 
but an input line is to be returned from the terminal. 


TERMPUT = 
Specifies the TPUT options requested. PUTGET issues a TPUT SVC to 
write the message to the terminal. This operand is used to indicate which of 
the TPUT options you want to use. The TPUT options are EDIT, ASIS or 
CONTROL; WAIT or NOWAIT; NOHOLD or HOLD; and NOBREAK 
or BREAKIN. The default values are EDIT, WAIT, NOHOLD and 
NOBREAK. 


EDIT 
Specifies that in addition,to minimal editing (see ASIS), the following TPUT 
functions are requested: 


1. Any trailing blanks are removed before the line is written to the 
terminal. If a blank line is sent, the terminal vertically spaces one line. 


2. Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 


3. All terminal control characters (for example: bypass, restore, horizontal 
tab, new line) are replaced with a printable character. Backspace is an 
exception; see item 4 under ASIS. 


ASIS 
Specifies that minimal editing is to be performed by TPUT as follows: 


1. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program caused I/O errors. This does not mean that all unprintable 
characters will be eliminated. Restore, upper case, lower case, bypass, 
and bell ring, for example, might be valid but nonprinting characters at 
some terminals. (See CONTROL.) 


2. Transmission control characters are added. 


3. EBCDIC NL, placed at the end of the message, indicates to the TPUT 
SVC that the cursor is to be returned at the end of the line. NL is 
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J 


J 


replaced with whatever is necessary for that particular terminal type to 
cause the cursor to return. This NL processing occurs only if you 
specify ASIS, and the NL is the last character in your message. 


If you specify EDIT, NL is handled as described in item 3 under EDIT. 


If the NL is embedded in your message, it is sent to the terminal as a 
cursor return. No idle characters are added (see item 6 below). This 
may cause overprinting, particularly on terminals that require a line-feed 
character to position the cursor on a new line. 


4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, TPUT attempts alternate methods to accomplish the 
backspace. 


5. Control characters are added as needed to cause the message to occur 
on several lines if the output line is longer than the terminal line size. 


6. Idle characters are sent at the end of each line to prevent typing as the 
cursor returns. 


No line continuation checking is done. 


CONTROL 
Specifies that this line is composed of terminal control characters and will 
not display or move the cursor on the terminal. This option should be used 
for transmission of characters such as bypass, restore, or bell ring. 


WAIT 
Specifies that control will not be returned to the program that issued the 


PUTGET until the output line has been placed into the terminal output 
buffer. 


NOWAIT 
Specifies that control should be returned to the program that issued the 
PUTGET macro instruction, whether or not a terminal output buffer is 
available. If no buffer is available, a return code of 16 (decimal) is returned. 


NOHOLD 
Specifies that control is to be returned to the program that issued the 
PUTGET macro instruction, and it can continue processing as soon as the 
output line has been placed on the output queue. 


HOLD 
Specifies that the program that issued the PUTGET macro instruction 
cannot continue its processing until the output line has been put out to the 
terminal or deleted. 


NOBREAK 
Specifies that if the terminal user has started to enter input, he is not to be 
interrupted. The output message is placed on the output queue to be 
displayed after the terminal user has completed the line. 
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BREAKIN 
Specifies that output has precedence over input. If the user at the terminal 
is transmitting, he is interrupted, and this output line is sent. Any data that J 
was received before the interruption is kept and displayed at the terminal 
following this output line. 


TERMGET = 
Specifies the TGET options requested. PUTGET issues a TGET SVC to 
bring in a line of data. This operand is used to indicate to the TGET SVC 
which of the TGET options you want to use. The TGET options are EDIT 
or ASIS, and WAIT or NOWAIT. The default values are EDIT and 
WAIT. 


EDIT 
Specifies that in addition to minimal editing (see ASIS), the buffer is filled 


out with trailing blanks. 


ASIS 
Specifies that minimal editing is done as follows: 


1. Transmission control characters are removed. 

2. The line of input is translated from terminal code to EBCDIC. 
3. Line deletion and character deletion editing is performed. 

4. Line feed and cursor return characters, if present, are removed. 


No line continuation checking is done. 


WAIT ) 


Specifies that control is to be returned to the program that issued the 
PUTGET macro instruction, only when an input message has been read. 


NOWAIT 
Specifies that control should be returned to the program that issued the 
PUTGET macro instruction whether or not a line of input is available. Ifa 
line of input is not available, a return code of 20 (decimal) is returned in 
register 15. 


ENTRY = entry point address 
(15) 
Specifies the entry point of the PUTGET service routine. If ENTRY is 
omitted, the PUTGET macro expansion generates a LINK macro 
instruction to invoke the PUTGET service routine. The address may be any 
address valid in an RX instruction or (15) if you load the entry point 
address into general register 15. 


MF=E 
Indicates that this is the execute form of the PUTGET macro instruction. 


listaddr 

(1) 
The address of the four-word input/output parameter list (IOPL). This can 
be a completed IOPL that you have built, or it may be 4 words of declared | 
storage that will be filled from the PARM, UPT, ECT, and ECB operands J 
of this execute form of the PUTGET macro instruction. The address must 
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be any address valid in an RX instruction or (1) if you have loaded the 
parameter list address into general register 1. 


SUBSTACK 
For CLIST processing, YES indicates that normal stack operations continue 
until PUTGET reaches a barrier element. PUTGET then passes the caller a 
return code indicating that CLIST processing completed. The barrier 
element remains on the stack until the caller explicitly deletes it. NO is the 
default value and indicates that the barrier feature is not used. 


Note: If the caller issues PUTGET without SUBSTACK = YES, and a 
barrier element exists on the input stack, normal stack operations continue 
until PUTGET reaches the barrier element. In foreground mode, PUTGET 
then treats the barrier element as a terminal element. In background mode, 
PUTGET passes an end-of-data return code to the caller. Processing 
contiues in this manner until the caller explicitly deletes the barrier element. 


Note: In the execute form of the PUTGET macro instruction, only the following 
is required: 


sa ait = 
(1) 


The PARM, UPT, ECT, and ECB operands are not required if you have built 
your IOPL in your own code. 


The output line address is not specifically required in the execute form of the 
PUTGET macro instruction, but must be coded in either the list or the execute 
form. 


The other operands and sublists are optional because you may have supplied them 
in the list form of the macro instruction or in a previous execute form, or because 
you may want to use the default values which are automatically supplied by the 
macro expansion itself. 


The ENTRY operand need not be coded in the macro instruction. If it is not, a 
LINK macro instruction is generated by the PUTGET macro expansion to invoke 
the PUTGET service routine. 


The operands you specify in the execute form of the PUTGET macro instruction 
set up control information used by the PUTGET service routine. You can use the 
PARM, UPT, ECT, and ECB operands of the PUTGET macro instruction to 
build, complete, or modify an IOPL. The OUTPUT, TERMPUT, and 
TERMGET operands and their sublist operands initialize the PUTGET 
parameter block. The PUTGET parameter block is referenced by the PUTGET 
service routine to determine which functions you want PUTGET to perform. 
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Building the PUTGET Parameter Block (PGPB) 


When the list form of the PUTGET macro instruction expands, it builds a - 
four-word PUTGET parameter block (PGPB). This PGPB combines the 
functions of the PUTLINE and the GETLINE parameter blocks and contains 
information used by the PUT and the GET functions of the PUTGET service 
routine. The list form of the PUTGET macro instruction initializes this PGPB 
according to the operands you have coded in the macro instruction. This 
initialized block, which you may later modify with the execute form of the 
PUTGET macro instruction, indicates to the PUTGET service routine the 
functions you want performed. It also contains a pointer to the output line 
descriptor that describes the output message and it provides a field into which the 
PUTGET service routine places the address of the input line returned from the 
input source. 


You must pass the address of the PGPB to the execute form of the PUTGET 
macro instruction. Since the list form of the macro instruction expands into a 
PGPB, all you need do is pass the address of the list form of the macro 
instruction to the execute form as the PARM value. 


The PUTGET parameter block is defined by the IKJPGPB DSECT. 
Figure 12-31 describes the contents of the PUTGET parameter block. 
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umber 
» = Contents or Meaning 


PUT control flags. These bits describe the output line to the PUTGET 
service routine. 


Always zero for PUTGET. 

The output line is a single level message. 
Must be zero for PUTGET. 

The output line is a multilevel message. 

The output line is a PROMPT message. 
Reserved. 


The output line is a MODE message. 
BYPASS processing is requested. 
ATTN processing is requested. 
Reserved. 


TPUT options field. These bits indicate to the TPUT SVC which of the 
TPUT options you want to use. 


Always set to 0 for TPUT. 


WAIT processing has been requested. Control will be returned to the 
issuer of TPUT only after the output line has been placed into a 
terminal output buffer. 


NOWAIT processing has been requested. Control will be returned to 
the issuer of TPUT whether or not a terminal output buffer is available. 


NOHOLD processing has been requested. The issuer of the TPUT can 


resume processing as soon as the output line has been placed on the 
output queue. 


HOLD processing has been requested. The issuer of the TPUT is not to 
resume processing until the output line has been written to the terminal 
or deleted. 


NOBREAK processing has been requested. The output line will be 
displayed only when the terminal user is not entering a line. 


BREAKIN processing has been requested. The output line is to be sent 
to the terminal immediately. If the terminal user is entering a line, he is 
to be interrupted. 


EDIT processing has been requested. 

ASIS processing has been requested. 
CONTROL processing has been requested. 
Reserved. 

Reserved. 

The address of the output line descriptor. 
GET control flags. 


Always zero for PUTGET. 
TERM processing is requested. 
Reserved bits. 


Reserved. 


Figure 12-31 (Part 1 of 2). The PUTGET Parameter Block 
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umber 
of = Contents or Meaning 


TGET options field. These bits indicate to the TGET SVC which of the 
TGET options you wish to use. 


Always set to | for TGET. 


WAIT processing has been requested. Control will be returned to the 
issuer of the TGET SVC only after an input message has been read. 


NOWAIT processing has been requested. Control will be returned to 
the issuer of the TGET SVC whether or not a line of input is available. 
If no line was available, PUTGET returns a code of 20 (decimal) in 
general register 15. 


EDIT processing has been requested. In addition to the editing 
provided by ASIS processing, the input buffer is to be filled out with + 
trailing blanks to the next doubleword boundary. 


..01 ASIS processing has been requested. (See the ASIS operand of the 


PUTGET macro instruction description.) 
XX. XX.. Reserved bits. 


Byte 2 
XXXX XXXX 


PGPBIBUF 


Reserved. 


The address of the input buffer. The PUTGET service routine fills this 
field with the address of the input buffer in which the input line has 
been placed. 


Figure 12-31 (Part 2 of 2). The PUTGET Parameter Block 


Types and Formats of the Output Line 


The PUTGET service routine writes only conversational messages to the terminal, 
it does not handle data lines. For information on how to write a data line or a 
nonconversational message to the terminal, see the section on the PUTLINE 
macro instruction. 


PUTGET accepts two output line formats depending upon whether the message 
you provide is a single level message or a multilevel message. 


Single Level Messages: A single level message is composed of one or more 
message segments to be formatted and written to the terminal with one execution 
of the PUTGET macro instruction. 


Multilevel Messages: A multilevel message is composed of one or more segments 
to be formatted and written to the terminal, and one or more message segments to 
be formatted and written to the terminal in response to question marks entered 
from the terminal. Note, however, that if you specify MODE in the PUTGET 
macro instruction, you can process only single level messages. If you specify 
PROMPT and TERMGET= EDIT in the PUTGET macro instruction, then 
second level messages will be written to the terminal, one at a time, in response to 
successive question marks entered from the terminal. If PROMPT messages are 
to be available to the user at the terminal, however, the top element of the input 
stack must not specify a procedure element as the current source of input, and the 
terminal user must not have inhibited prompting. (See the PROFILE command 
in TSO/E Command Language Reference.) 
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Passing the Message Lines to PUTGET 


C You must build each of the message segments to be processed by the PUTGET 
service routine as if it were a line of single line data. The segment must be 
preceded by a four-byte header field -- the first two bytes containing the length of 
the segment including the header, and the second two bytes containing zeros or an 
offset value if you use the text insertion facility provided by PUTGET. This 
message line format is required whether the message is a single level message or a 
multilevel message. 


Because of the additional functions performed on message lines -- message ID 
stripping, text insertion, and multilevel processing -- you must provide the 
PUTGET service routine with a description of the line or lines that are to be 
processed. This is done with an output line descriptor (OLD). 


There are two types of output line descriptors. The type depends on whether the 
messages are single level or multilevel. 


The OLD required for a single level message is a variable length control block 
which begins with a fullword value representing the number of segments in the 
message, followed by fullword pointers to each of the segments. 


The format of the OLD for multilevel messages varies from that required for 
single level messages in only one respect. You must preface the OLD witha 
fullword forward-chain pointer. This chain pointer points to another output line 
descriptor or contains zero to indicate that it is the last OLD on the chain. 
Figure 12-32 shows the format of the output line descriptor. 


YW Number 
of = Contents or Meaning 


The address of the next OLD, or zero if this is the last one on the chain. 
This field is present only if the message pointed to is a multilevel 
message. 


The number of message segments pointed to by this OLD. 
The address of the first message segment. 


The address of the next message segment. 


The address of the nth message segment. 
Figure 12-32. The Output Line Descriptor (OLD) 


You must build the output line descriptor and pass its address to the PUTLINE 
service routine as the OUTPUT operand address in either the list or the execute 
form of the macro instruction. When the macro instruction expands, it places this 
OLD address into the second word of the PUTLINE parameter block. 


Figure 12-33 shows the two control block structures possible when passing an 
output message to the PUTGET service routine. Note that MODE, TERM, or 
ATTN may not be coded in the PUTGET macro instruction if you want to 
provide multilevel messages to the terminal. (Mode messages can have only one 
level.) 


Message segments for PUTGET must follow the same rules as those for 

PUTLINE informational processing. (See the section on “Stripping Message 
C Identifiers.”) Note that if a PUTGET message segment does not contain at least 

one blank, a return code of 24 (invalid parameters) will be received in register 15. 
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PUTGET 
Service 
Routine 
Single Level Message 


OLD 


| 
rr es | 


ae 
amen: 
= 


4 Next OLD 


| 


Segment n 


Multi- Level Messages 


MODE OLD 


TERM may not be specified. 
ATIN | 00000000 


4 Segment | 
h Segment 2 
| 


Figure 12-33. Control Block Structures for PUTGET Output Messages 
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C 


PUTGET Processing 


Text insertion and message identifier stripping are available to all output messages 
processed by the PUTGET service routine. For a detailed description of these 
functions see “PUTLINE Message Line Processing.” 


The PUTGET service routine provides other processing capabilities dependent 
upon whether the message is a mode or a prompt message. 


Mode Message Processing: A mode message is a message put out to the terminal 
when a command or a subcommand is anticipated. The processing of mode 
messages by the PUTGET service routine is dependent upon the following two 
conditions: 


1. Are you providing an output line? 
2. From what source is the input line coming? 


Is an Output Line Present: You need not provide an output line to the PUTGET 
service routine. If you do provide an output line address then PUT processing 
will take place. Whether your output line is written to the terminal is then 
dependent upon the input source indicated by the input stack. If you do not 
provide an output line (OUTPUT =0) then only the GET function of the 
PUTGET service routine takes place. 


What is the Input Source: The source of the input line, as determined by the top 
element of the input stack, determines the type of processing performed by the 
PUTGET service routine. You can override the input stack by coding the TERM 
or ATTN operands in the PUTGET macro instruction. The two sources of input 
supported are: 


1. Terminal 
2. In-storage 


If the current source of input is the terminal, and you provide an output line, the 
PUTGET service routine writes the line to the terminal, returns a line from the 
terminal, and places the address of the returned line into the fourth word of the 
PUTGET parameter block. If the line returned from the terminal is a question 
mark, however, the PUTGET service routine causes the second level message (if 
one exists) to be written to the terminal, again puts out the mode message, and 
then returns a line from the terminal. If the user at the terminal enters a question 
mark in response to a mode message, and no second level message exists, 
PUTGET puts out the message “IK J667601 NO INFORMATION 
AVAILABLE,” puts the mode message out again, and returns a line from the 
terminal. 


Note that if the user enters a question mark from the terminal, the second level 
message returned to the terminal is not related to the current mode message but 
to the command processor just terminated; mode messages can have only one 
level. 


If the current source of input is an in-storage list, the output line (if you provide 
one) is ignored and the PUTGET service routine normally obtains an input line 
from the in-storage list and places a pointer to that line in the fourth word of the 
PGPB. If however, a second level message exists, PUTGET will only return a 
line if the user at the terminal has access to the information in the chain through 
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the PAUSE mechanism. If the chain is not available to the user, no line is 
obtained by PUTGET, and it returns a code of 12 in register 15. You can test 

this return code, and if you want, recover from this error condition by turning on - 
the high order bit of the ECTMSGF field of the environment control table and 
reissuing the PUTGET. The second level message is then purged and a line is 
obtained from the in-storage list. 


Pause Processing: If the terminal user has requested the PAUSE option on the 
PROFILE command, the PUTGET service routine makes the second level 
messages available to him, even if the current input source is not the terminal. 


PAUSE processing works as follows. If a second level message does exist, 
PUTGET puts out the message “IKJ56762A PAUSE” to the terminal informing 
the terminal user that PAUSE processing is in effect. At this point the terminal 
user can enter either a question mark to indicate that he wishes to have the 
second level messages put out to the terminal, or press the ENTER key to 
indicate that the information is not needed. If the user presses the ENTER key, 
the second level message is eliminated. If he enters any response other than a 
question mark or hitting the ENTER key, PUTGET prompts him for a correct 
response. 


Prompt Message Processing: A prompt message is a message put out to the 
terminal when the program in control requires input from the terminal user. 
PROMPT information must come from the terminal and can not be obtained 
from any other source of input. There are three cases when a request for 
PROMPT processing is denied by PUTGET: 


@ When the current source of input, as determined by the top element of the ) 
input stack, is an in-storage procedure that 1s not an EXEC command 
procedure. 


@ When the NOPROMPT attribute is specified in the user’s profile table (UPT). 


@e When an EXEC command procedure, executing in the background, does not 
have a DATA PROMPT entry to satisfy the request or a PROMPT control 
statement. 


When the PUTGET service routine returns control to the program that invoked 
it, it returns a return code of 12 when no prompting was allowed on a PROMPT 
request because: 


e The current source of input is an in-storage list other than an EXEC 
command procedure. 


e The NOPROMPT attribute is specified in the user’s profile table (UPT). 


e The current source of input is an EXEC command procedure running in the 
background, and there is no DATA PROMPT entry to satisfy the request. 


If PROMPT processing is allowed, the PUTGET service routine writes the first 

level message to the terminal and obtains an input line from the terminal. If the 

input line is a question mark, PUTGET either returns the next level message 

provided, or a message informing the user that no information 1s available. a 
PUTGET continues to respond to question marks entered from the terminal by 
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writing one more second level message to the terminal in response to each 
question mark entered until the chain is exhausted; at that point PUTGET issues 
a message informing the user at the terminal that no more information is 
available. The prompt message is not repeated and the task goes into an input 
wait until the terminal user enters a line. When a line is obtained from the 
terminal, PUTGET places the address of the line into the fourth word of the 
PGPB. 


Note that for message prompting, PUTGET with TERMGET = EDIT is required. 
Input Line Format - The Input Buffer 


The fourth word of the PUTGET parameter block contains zeros until the 
PUTGET service routine returns a line of input. The service routine places the 
requested input line into an input buffer beginning on a doubleword boundary 
located in subpool 1. It then places the address of this input buffer into the 
fourth word of the PGPB. The input buffer belongs to the program that issued 
the PUTGET macro instruction. The buffer or buffers returned by PUTGET are 
automatically freed when your code relinquishes control. You may free the input 
buffer with the FREEMAIN macro instruction after you have processed or 
copied the input line. 


Regardless of the source of input, the input line returned by the PUTGET service 
routine is in a standard format. All input lines are in the variable length record 
format with a fullword header followed by the text returned by PUTGET. 

Figure 12-34 shows the format of the input buffer returned by the PUTGET 
service routine. 


Figure 12-34. Format of the PUTGET Input Buffer 


The two-byte length field contains the length of the returned input line including 
the header (4 bytes). You can use this length field to determine the length of the 
input line to be processed, and later, to free the input buffer with the R form of 
the FREEMAIN macro instruction. The two-byte offset field is always set to 
zero on return from the PUTGET service routine. 
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Figure 12-35 shows the PUTGET control block structure for a multilevel 
PROMPT message after the PUTGET service routine has returned an input line. 


J 


PUTGET 
Service 
Routine 


Output Message 
OLD 


4 Next OLD 


4 Segment 2 


4 Segment n 


OLD 


00000000 ) 
| 


Input Line 


[lengrh [Ofer [Date 


Figure 12-35. PUTGET Control Block Structure - Input Line Returned 


An Example of PUTGET 
Figure 12-36 is an example of the code required to execute the PUTGET macro 
instruction. The code uses a multilevel PROMPT message as the PUTGET 


output line. It assumes that a line of input will be returned from the terminal and 
tests only for a zero return code (PUTGET completed normally). 


2 
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The execute form of the PUTGET macro instruction builds the 1/O parameter 
list, using the addresses of the user profile table and the environment control table 
supplied in the command processor parameter list. In addition, the I/O parameter 
list contains the address of an ECB built by the code, and the address of the list 
form of the PUTGET macro instruction as the PUTGET parameter block 
address. 


Note that the TERMPUT, TERMGET, and ENTRY operands are not coded; the 
default values are used. Note also that this code is effective only if the top 
element of the input stack indicates a terminal as the current source of input. 
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Figure 12-36 (Part 1 of 3). Coding Example - PUTGET Multilevel PROMPT Message 
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Figure 12-36 (Part 2 of 3). Coding Example - PUTGET Multilevel PROMPT Message 
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Figure 12-36 (Part 3 of 3). Coding Example - PUTGET Multilevel PROMPT Message 
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Return Codes from PUTGET 


When the PUTGET service routine returns control to the program that invoked 
it, it provides one of the following return codes in general register 15. 


Code 
(decimal) 


0 


12 


12 


16 
20 
24 


28 


32 


40 


Meaning 


PUTGET completed normally. 
The line obtained came from the terminal. 


PUTGET completed normally. 
The line obtained did not come from the terminal. (MODE messages only.) 


The PUTGET service routine did not complete. An attention interruption occurred during 
the execution of PUTGET, and the attention handler turned on the completion bit in the 
communications ECB. 


No prompting was allowed on a PROMPT request. Either the user at the terminal 
requested no prompting with the PROFILE command, or the current source of input is an 
in-storage list other than an EXEC command procedure. 

A line could not be obtained after a MODE request. Second level messages exist, and the 
current stack element is not a terminal, but the terminal user did not request PAUSE 


processing with the PROFILE command. The messages are, therefore, not available to 
him. 


The NOWAIT option was specified for TPUT and no line was put out. 
The NOWAIT option was specified for TGET and no line was received. 
Invalid parameters were supplied to the PUTGET service routine. 


A conditional GETMAIN was issued by PUTGET for output buffers and there was not 
sufficient space to satisfy the request. 


The terminal has been disconnected. 


A barrier element is on the top of the stack and SUBSTACK = YES was specified. No 
command buffer is passed back. 


Note: User abend 204 is issued by the TMP when the return code is greater than 
12 and less than 40. 
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Chapter 13. Using the TGET/TPUT/TPG SVC for Terminal I/O 


SVC 93, a supervisor call routine, provides a route for program I/O to and from 
the terminal. You use the TGET, TPUT, and TPG macro instructions to invoke 
SVC 93. The basic sequential access method (BSAM), the queued sequential 
access method (QSAM), and the TSO I/O service routines all use SVC 93 to 
process terminal I/O. You may use the TGET, TPUT, and TPG macro 
instructions in any TSO routines you write, and in any application programs that 
run under TSO. However, when you use TGET, TPUT, or TPG in an 
application program, the program becomes TSO-dependent. 


In a batch environment, the only TPUTs that are processed are those with the 
ASID, ASIDLOC, or USERIDL keyword referencing an ASID or userid other 
than the current one. TGET, TPG, and other types of TPUT macros are ignored. 


The TGET, TPUT, and TPG macro instructions do not require that you build . 
control blocks for their use. The operands you code into each of these macro 
instructions specify the location and size of the TGET, TPUT, or TPG biffers, 
and the SVC functions you want performed. 


The TGET and TPUT macro instructions have standard, list, execute, and 
register forms. The TPG macro has standard, list, and execute forms. 


This section discusses: 


The TPUT macro instruction 

The TPG macro instruction 

The TGET macro instruction 

Formatting the TGET/TPUT/TPG parameter registers 
Examples of TGET and TPUT 


The TPUT Macro Instruction -- Writing a Line to the Terminal 


Use the TPUT macro instruction (SVC 93) to transmit a line of output to the 
terminal. You can use the TPUT macro instruction in any TSO routines you 
write, and in any application programs to be run under TSO. Note, however, 
that TPUT does not provide message ID stripping, text insertion, or second level 
message chaining. If you require these features, use the PUTLINE macro 
instruction. 


The TPUT macro instruction can be issued in 24-bit or 31-bit addressing mode. 


TPUT executes in 24-bit addressing mode. All input specified on the macro must 
reside below 16 Mb in virtual storage. 
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Figure 13-] shows the format of the TPUT macro instruction; the figure 
combines the standard, register, list, and execute forms. Each of the operands is 
explained following the figure. Appendix A describes the notation used to define 
macro instructions. 


Note: For a discussion of register contents and parameter list expansions for 
TPUT, see “TGET/TPUT/TPG Parameter Formats” later in this section. 


[symbol] TPUT buffer address,buffer size 

,EDIT 

,NOEDIT 

,ASIS ,NOHOLD| | ,NOBREAK 

,CONTROL ,NOWAIT ,HOLD , BREAKIN 

,FULLSCR 

,R ,HIGHP| ;, ASID=id 

»MF= JL , LOWP ,ASIDLOC=address 
(E,ctrladdr) , USERIDL=address 


Figure 13-1. The TPUT Macro Instruction -- Standard, Register, List, and Execute Forms 


buffer address 
Standard form: The address of the buffer that holds your line of output. 
You may specify any label valid in an RX instruction, or place the address 
of the label in one of the general registers 1-12, and then specify that 
register within parentheses. 


Register form: The register that contains the parameters to be passed in 
register 1 to the TPUT SVC. When the R format is specified, this operand 
must be in one of the general registers 1-12, and that register specified 
within parentheses. 


buffer size 
Standard form: The size of the output buffer in bytes. The allowable range 
is from 0 through 32,767 bytes. A buffer size of 0 results in no data being 
transmitted to the terminal. You can specify this buffer size directly as a 
number, or you can place the buffer size into one of the general registers 0, 
or 2-12, and specify that register within parentheses. 


Register form: The register that contains the parameters to be passed in 
register 0 to the TRPUT SVC. When the R format is specified, this operand 
must be in one of the general registers 0 or 2-12, and that register specified 
within parentheses. 


Notes: 


1. Ifthe registers you specify as the first and second operands in the 
register form of TPUT are registers 1 and 0 respectively, the TPUT 


macro instruction will expand directly into the TGET/TPUT/TPG SVC. 


However, if you use registers 2-12, the macro expansion will load 
registers | and 0 from the registers you specify before issuing the SVC. 
Therefore, you might find it advantageous to use registers 1 and 0. 
(The expansion destroys the contents of registers 1 and 0.) 
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R 


If QSAM is used for terminal I/O and a data set is defined with 
BLKSIZE=80 and RECFM =U, each line will be truncated by 1 
character. This byte (the last byte) is reserved for an attribute 
character. 


Indicates that this is the register form of the TPUT macro instruction. You 
must place the parameters you want passed to the TPUT SVC into two 
registers and specify those registers as the first two operands of the macro 
instruction. 


The R operand and all other optional operands are mutually exclusive. 


If both R and any other optional operands are coded, the macro will not 
expand. 


MF= 


Indicates the form of the TPUT macro instruction. 


L 


Specifies the list form. 


(E,ctri addr) 


EDIT 


Specifies the execute form and the address of the list form. 


Indicates that in addition to minimal editing (see ASIS), the following 
TPUT functions are requested: 


l. 


All trailing blanks are removed before the line is written to the terminal. 
If a blank line is sent, the terminal vertically spaces one line. 


Control characters are added to the end of the output line to position 
the cursor to the beginning of the next line. 


All terminal control characters (except backspace) are replaced with a 
printable character. 


Only those characters that appear in USA EBCDIC keyboard layout 
and code charts are supported. All others are replaced with a printable 
character. The replacement of characters includes the representation of 
the keyboard features and national characters without hexadecimal 
equivalents of the USA EBCDIC code. 


EDIT is the default value for the EDIT, ASIS, CONTROL, FULLSCR, 
and NOEDIT operands. 


NOEDIT 


Indicates that, if the terminal is an IBM 3270 display, the message is 
transmitted completely unedited. It is assumed that the command processor 
using this full-screen option has structured the data stream with the 
necessary commands to perform the display function. For LU_T1 
terminals, this option is converted to ASIS. 
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TSO/VTAM supports 3270 extended data stream functions via the TPUT 
NOEDIT and NOEDIT modes of input. For information about specifying 
the NOEDIT mode of input, refer to “STFSMODE -- Set Full-Screen 
Mode” on page 14-15. 


ASIS 
Indicates that minimal editing is to be performed by the TPUT SVC as 
follows: 


1. The line of output is translated from EBCDIC to terminal code. 
Invalid characters are converted to a printable character to prevent 
program caused I/O errors. This does not mean that all unprintable 
characters are eliminated. For example, restore, uppercase, lower case, 
bypass, and bell ring might be valid but unprintable characters at some 
terminals. (See CONTROL.) 


2. Transmission control characters are added. 


3. An EBCDIC NL, placed at the end of the message, indicates to the 
TPUT SVC that the cursor is to be returned at the end of the line. NL 
is replaced with whatever is necessary to cause the cursor to return for 
that particular terminal type. This NL processing occurs only if you 
specify ASIS, and if the NL is the last character in your message. 


If you specify EDIT, NL is handled as described in item 3 under EDIT. 


If the NL is embedded in your message, a semicolon or colon may be 
substituted for NL and sent to the terminal. No idle characters are 
added (see item 6 below). This may cause overprinting, particularly on 
terminals that require a line-feed character to position the carrier on a 
new line. 


4. If you have used backspace in your output message, but the backspace 
character does not exist on the terminal type to which the message is 
being routed, the backspace character is removed from the output 
message. 


5. If the output line is longer than the terminal line size, control characters 
are added as needed to cause the message to display on several lines. 


6. A sufficient number of idle characters is added to the end of each 
output line to prevent the transmission of output to the terminal while 
the cursor is being returned to the left-hand margin. 


7. Including a bypass character, bypass carriage return, or bypass new-line 
character in the TPUT macro data suppresses printing of the next input 
entered by the user at the 3270 terminal. VITAM moves the cursor to 
the next available line, unlocking the keyboard. No more data is sent 
to the terminal until the terminal user enters data or presses the 
ENTER key. The data entered by the user is not printed at the 
terminal. 
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CONTROL 
Indicates that this line is composed of terminal control characters and does 
not display or move the cursor on the terminal. This option should be used 
for transmission of characters such as bypass, restore, or bell ring. See item 
7 under ASIS for additional information. 


FULLSCR 
Indicates that, for IBM 3270 display terminals, the message will be 
transmitted essentially unedited. The FULLSCR option is designed to 
allow you to use special features of the 3270 system. For any other terminal 
type, this option is treated exactly as ASIS. With the FULLSCR option, 
only the following editing is performed: 


1. If the first character in your message is an escape control character 
(X‘27’), the two following characters are treated as a command code 
and as a write control character by the 3270. Note that the command 
code should always be for a remote 3270. If necessary, TPUT will 
convert the code to that for a local 3270. If the first character is not an 
escape character, a default write command and a write control character 
are added to the beginning of the message. Any attachment-dependent 
characters required for correct transmission of the data stream are 
provided by the access method. 


2. Transmission control characters (SOH, STX, ETX, ETB, EOT, and 
NAK) and characters having no 3270 equivalent (X‘04’, X‘*06’, X‘14’ 
through X‘17’, and X‘24’) are converted to printable colons to prevent 
program-caused I/O errors. 


Lines are not counted when you use this option. 


If the OWAITHI value specified in your TSO parameters is not large 
enough to contain your entire message, or if the BUFFERS and 
BUFFERSIZE parameters are specified so that your message does not fit 
into all of the system’s buffers, the TPUT operation does not proceed, and 
code X‘10’ is returned. For a description of OWAITHI, refer to SPL: 
Initialization and Tuning. Without the FULLSCR option, your TPUT 
proceeds buffer-by-buffer as buffers become available. 


If FULLSCR is specified for a message destined for another terminal, ASIS 
will be used instead. 


WAIT 
Specifies that control is not returned to the program that issues the TPUT 
macro instruction until the output line is placed into a terminal output 
buffer. If no buffers are available, the issuing program is placed into a wait 
state until buffers become available, and the output line is placed into them. 
WAIT is the default value for the WAIT and NOWAIT operands. 


NOWAIT 
Specifies that control is returned to the program that issues the TPUT 
macro instruction, whether or not a terminal output buffer is available for 
the output line. If no buffer is available, the TPUT SVC returns a code of 
04 in register 15. 
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NOHOLD 
Indicates that control is returned to the program that issues the TPUT 
macro instruction as soon as the output line is placed in terminal output 
buffers. 


NOHOLD is the default value for the NOHOLD and HOLD operands. 


HOLD 
Specifies that the program that issues the TPUT macro instruction cannot 
continue its processing until this output line is written to the terminal or 
deleted. The TPUT macro with the HOLD option is not discarded during 
RESHOW processing. 


NOBREAK 
Specifies that if the user starts to enter input, the user is not interrupted. 
The output message is placed on the output queue and displayed after the 
user completes the line. 


NOBREAK is the default value for the NOBREAK and BREAKIN 
operands. 


BREAKIN 
Specifies that output has precedence over input. If the user starts to enter 
input, he is interrupted, and this output line is displayed. Any data received 
before the interruption is displayed following this output line. 


HIGHP 
Specifies that this message must be sent to the terminal, even though the 
destination terminal does not display messages from other terminals. This 
operand counters the effect of the interterminal communication bit when the 
bit is set by the TERMINAL command. (The HIGHP operand is used by 
the SEND subcommand of OPERATOR and the SEND operator 
command.) The operand is recognized only if the issuing task is authorized 
(via system key, supervisor state, or APF). The ASID keyword must also 
be specified. HIGHP is the default if neither HIGHP nor LOWP is 
specified, and if the issuing program is authorized. 


LOWP 
Specifies that, if the user of the destination terminal allows interterminal 
messages, this TPUT will be sent to the terminal. (TPUT tests the 
interterminal communication bit in the terminal status block.) If such 
messages are not allowed, the message is not displayed, and a code of X‘0C’ 
is returned, indicating that the message was not displayed. The LOWP 
operand is recognized only when ASID is specified. The issuer must be 
authorized (via system key, supervisor state, or APF). 


If LOWP is specified, the issuing program should have an alternate method 
of transmitting the message to the terminal user. For example, a message 
data set could be used. 


ASID, ASIDLOC, or USERIDL 
Specifies the ASID (address space identifier) of the target terminal, the 
address of that ASID, or the address of a field that contains a user ID. 
This facility is used for supervisor communication with the terminal and for 
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J 


J 


Return Codes from TPUT 


inter-user communication among terminals (the SEND command). If you 
specify ASID, you must supply an ASID number. The ASID is located in 
the two-byte JSCBTJID field of the job step control block. If you use 
ASIDLOC, you must supply the address of the halfword that contains the 
ASID. If you use USERIDL, you must supply the address of the eight-byte 
field that contains the user ID. The user ID must be left-justified and, if 
necessary, padded with blanks. ASID, ASIDLOC, or USERIDL can be 
specified in a register (2-12), and must be right-justified. The register 
number must be enclosed in parentheses. If USERIDL 1s used, the 
NOHOLD option is both required and the default if not specified. 


ASID, ASIDLOC, and USERIDL are invalid when you specify them with 
FULLSCR or ASIS parameters. 


Note: Normally, a program invokes TPUT to issue a message to the user 
running that program -- that is, ASID, ASIDLOC, and USERIDL are not 
specified. If that program is run in the background, the TPUT has no 
effect. If the TPUT specifies an ASID or userid, the message is sent to the 
target terminal. ASID and USERID TPUTs from programs not in 
supervisor state or not authorized under APF are prefixed with a plus sign 
(+) by SVC 93 to prevent possible counterfeiting of system messages to an 
operator console. 


When it returns control to the program (foreground or background) that invoked 
it, the TPUT SVC supplies one of the following return codes in general register 


15: 

Code Meaning 

(hexadecimal) 

00 TPUT completed successfully. 

04 NOWAIT was specified and no terminal output buffer was available. 

08 An attention interruption occurred while the TPUT SVC routine was processing. 
The message was not sent. 

0C A TPUT macro instruction with an ASID operand was issued but the user, 
indicated by the ASID, requested that interterminal messages not be printed on his 
terminal. The message was not sent. 

10 Invalid parameters were passed to the TPUT SVC. 

14 The terminal was logged off and could not be reached. 


The TPG Macro Instruction - Writing a Line Causing Immediate 


Response 


Use the TPG macro instruction (SVC 93) to transmit a line of output to the 
terminal if that line of output will cause the device to respond immediately with 
input. The main use of TPG is to perform the Query function for a user who has 
included a Read Partition Structured field. TPG NOEDIT creates an outbound 
request unit with an associated change direction indicator to allow the device to 
go into send state. This data is not inspected. A TGET macro must be issued to 
retrieve the query response. For an example of how the TPG and TGET macros 
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work together, see “(3) Write to and Get Information from the Terminal” on 
page B-3. 


You can use the TPG macro instruction in any TSO routines you write, and in 
any application programs to be run under TSO. 


Note: The TPG macro instruction is designed specifically to allow you to use the 
special features of the IBM 3279. 


The TPG macro instruction can be invoked in either 24-bit or 31-bit addressing 
mode. TPG executes in 24-bit addressing mode. All input specified on the macro 
must reside below 16 Mb in virtual storage. 


Figure 13-2 shows the format of the TPG macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. For a discussion of parameter list expansions 
for TPG, see “TGET/TPUT/TPG Parameter Formats” later in this section. 


[symbol] TPG buffer address,buffer size 
[,NOEDIT]| ,WAIT , NOHOLD 
,NOWAIT || , HOLD 
»;MF=| L 
(E,ctrladdr) 


Figure 13-2. The TPG Macro Instruction -- Standard, List, and Execute Forms 


buffer address 
Standard form: The address of the buffer that holds your output data. 
You may specify any address valid in an RX instruction, or place the 
address in one of the general registers 1-12, and then specify that register 
within parentheses. 


buffer size 
Standard form: The size of the output buffer in bytes. The allowable range 
is from 0 through 32,767 bytes. A buffer size of 0 results in no data being 
transmitted to the terminal. You can specify this buffer size directly as a 
number, or you can place the buffer size into one of the general registers 0, 
or 2-12, and specify that register within parentheses. 


Note: The R format may not be used for the TPG macro. 


NOEDIT 
Indicates that, if the terminal is an IBM 3270 display, the message is 
transmitted completely unedited. The command processor using this option 
must structure the data stream with the necessary commands to perform the 
display function (by including the command, write control character, 
structured fields,...). The command processor should supply only the data 
stream. Any attachment-dependent characters (such as X‘27’ for 
bisynchronous devices) are provided by the access method. For LU_T1 
terminals, this option is treated exactly like the ASIS option of the TPUT 
macro. 
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Note: NOEDIT ts the default, and only, mode for the TPG macro. If 
NOEDIT is omitted, a comma must be used. 


WAIT 
Specifies that control is not returned to the program that issued the TPG 
macro instruction until the output line is placed into a terminal output 
buffer. If no buffers are available, the issuing program is placed into a wait 
state until buffers become available, and the output line is placed into them. 
WAIT is the default value for the WAIT and NOWAIT operands. 


NOWAIT 
Specifies that control is returned to the program that issued the TPG macro 
instruction, whether or not a terminal output buffer is available for the 
output line. If no buffer is available, the TPG SVC returns a code of 04 in 
register 15. 


NOHOLD 
Indicates that control is returned to the program that issued the TPG macro 
instruction as soon as the output line is placed in terminal output buffers. 


NOHOLD is the default value for the NOHOLD and HOLD operands. 


HOLD 
Specifies that the program that issued the TPG macro instruction cannot 
continue its processing until this output line is written to the terminal or 
deleted. 


Indicates the form of the TPG macro instruction. 


L 
Specifies the list form. 


(E,ctrl addr) 
Specifies the execute form and the address of the list form. 


Note: If a TPG macro is coded in a background program, the TPG is 
ignored. 


Return Codes from TPG 


When it returns control to the program (foreground or background) that invoked 
it, the TPG SVC supplies one of the following return codes in general register 15: 


Code Meaning 

(hexadecimal) 

00 TPG completed successfully. 

04 NOWAIT was specified and no terminal output buffer was available. 

08 An attention interruption occurred while the TPG SVC routine was processing. The 


message was not sent. 
10 Invalid parameters were passed to the TPG SVC. 


14 The terminal was logged off and could not be reached. 
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The TGET Macro Instruction -- Getting a Line from the Terminal 


Use the TGET macro instruction to read a line of input from the terminal. A line J 
of input is defined as all the data between the beginning of the input line and a 

line-end delimiter. A line-end delimiter is any character or combination of 

characters that causes the cursor to return to the left-hand margin on a new line, 

or that terminates transmission from the terminal. 


You can use the TGET macro instruction in any TSO routine, and in any 
application program that is run under TSO. Note, however, that TGET does not 
provide access to in-storage lists, nor does it perform any type of logical line 
processing on the returned line. If you require these features, use the GETLINE 
macro instruction. 


Each time TGET returns control to your program, register 1 contains the number 
of bytes of data actually moved from the terminal to your input buffer. If your 
buffer is smaller than the line of input entered at the terminal, only as much of 
the input line as can be contained in the input buffer is moved. Return code 
X‘OC’ indicates that only part of the line was obtained by TGET. You must then 
issue as many TGET macro instructions as are required to get the rest of the line 
of input. 


The TGET macro instruction can be invoked in 24-bit or 31-bit addressing mode. 
TGET executes in 24-bit addressing mode. All input specified on the macro must 
reside below 16 Mb in virtual storage. 


Figure 13-3 shows the format of the TGET macro instruction; it combines the J 
standard and the register form. Each of the operands is explained following the 

figure. Appendix A describes the notation used to define macro instructions. For 

a discussion of register contents and parameter list expansions for TGET, see 
“TGET/TPUT/TPG Parameter Formats” later in this section. 


[symbol] TGET buffer address,buffer size | | MALE | 


(E,ctrladdr) 


Figure 13-3. The TGET Macro Instruction -- Standard, Register, List, and Execute Forms 


buffer address 
Standard form: The address of the buffer that is to receive the input line. 
This can be any address valid in an RX instruction, or the address can be 
placed in one of the general registers 1-12, and that register specified within 
parentheses. 


Register form: The register that contains the parameters to be passed in 
register 1 to the TGET SVC. When the R format is specified, this operand 
must be in one of the general registers 1-12, and that register specified 
within parentheses. 
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buffer size 
Standard form: The size of the input buffer in bytes. The allowable range 
is from 0 through 32,767 bytes. You can specify this buffer size directly as a 
number, or you can place the buffer size into one of the general registers 0, 
or 2-12, and specify that register within parentheses. A TGET with a 
0-length buffer size will successfully get a null line. 


Register form: The register that contains the parameters to be passed in 
register 0 to the TGET SVC. When the R format is specified, this operand 
must be in one of the general registers 0 or 2-12, and that register specified 
within parentheses. 


Note: If the registers you specify as the first and second operands in the 
register form of TGET are registers 1 and 0 respectively, the TGET macro 
instruction will expand directly into the TGET/TPUT/TPG SVC. However, 
if you use registers 2-12, the macro expansion will load registers 1 and 0 
from the registers you specify before issuing the SVC. Therefore, you might 
find it advantageous to use registers | and 0. 


Indicates that this is the register form of the TGET macro instruction. You 
must place the parameters you want passed to the TGET SVC into two 
registers and specify those registers as the first two operands of the macro 
instruction. 


The R operand and all other optional operands are mutually exclusive. If 
both R and any other optional operands are coded, the macro will not 
expand. 


EDIT 
Specifies that in addition to minimal editing (see ASIS), the following 
TGET functions are requested: 


1. All terminal control characters (nongraphic characters such as bypass, 
line feed, restore, prefix and the character immediately following it) are 


removed from the data. 


2. When backspace is not used for character deletion, the horizontal tab 
(HT) and the backspace (BS) characters remain in the data. 


3. If the returned input line is shorter than the input buffer length, the 
buffer is padded with blanks. These blanks are not included in the 
character count returned in register 1. 


EDIT is the default value for the EDIT and ASIS operands. 


ASIS 
Specifies that minimal editing is done as described below: 


1. Transmission control characters are removed. 


2. The returned input line is translated from terminal code to EBCDIC. 
Invalid characters are compressed out of the data. 
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3. Line deletion and character deletion are performed according to the 
specifications in the terminal status block. 


4. New line (NL), cursor return (CR), and line feed (LF) characters, if 
present at the end of the line, are not included in the data count 
returned in register 1. 


5. After the input message is received, the cursor is returned to the 
left-hand margin of the next line before any output to the terminal is 
displayed. 


WAIT 
Specifies that control is not returned to the program that issues the TGET 
macro instruction until the input line is placed into your input buffer. If an 
input line is not available from the terminal, the issuing program is placed 
into a wait state until a line becomes available and is read into your input 
buffer. WAIT is the default value for the WAIT and NOWAIT operands. 


NOWAIT 
Specifies that, whether or not an input line is available from the terminal, 
control is returned to the program that issues the TGET macro instruction. 
If no line is returned, the TGET SVC returns a code of X‘04 in register 15. 


MF = 
Indicates the form of the TGET macro instruction. 


L 
Specifies the list form. 


(E,ctrladdr) 
Specifies the execute form and the address of the list form. 


Return Codes from TGET 


When it returns control to the program that invokes it, the TGET SVC supplies, 
in register 1, the length of the message moved into your buffer, and, in register 15, 
one of the following return codes: 


Code Meaning 
(hexadecimal) 
00 TGET completed successfully. Register | contains the length of the input line read 


into your input buffer. 
04 NOWAIT was specified and no input was available to be read into your input buffer. 


08 An attention interruption occurred while the TGET SVC routine was processing. The 
message was not received. 


0c Your input buffer was not large enough to accept the entire line of input entered at 
the terminal. Subsequent TGET macro instructions will obtain the rest of the input 
line. 

10 Invalid parameters were passed to the TGET SVC. 

14 The terminal was logged off and could not be reached. 


13-12 TSO/E Guide to Writing a TMP or a CP 


18 TGET completed successfully. Register 1 contains the length of the input line read 
into your buffer. The data was received in NOEDIT mode. 


1C Your input buffer was not large enough to accept the entire line of input entered at 
the terminal. Subsequent TGET macro instructions will obtain the rest of the input 
line. The data was received in NOEDIT mode. 


TGET/TPUT/TPG Parameter Formats 


If you use the register format of the TGET or TPUT macro instruction, you must 
code the parameters you want passed to the TGET/TPUT/TPG SVC into two 
registers. Specify these two registers, enclosed in parentheses, as the first two 
operands of the TGET or TPUT macro instruction, followed by the R operand to 
indicate that you are executing the register form of the macro instruction. 


Note: For TPUT, the expansion destroys the contents of registers 0 and 1. 


If the registers you specify as the first and second operands of the macro 
instruction are register 1 and register 0 respectively, the TGET or TPUT macro 
instruction expands directly to the TGET/TPUT SVC. If you specify other 
permissible registers, registers 2-12, the macro expands to load registers one and 
zero from the registers you specify before issuing the SVC. The R format may 
not be used for the TPG macro. 


For the TPUT macro, the registers must be formatted as shown in Figure 13-4. 


Address Space ID (ASID-TPUT only) Buffer Size 
RO 
RI Address of your Input or Output Buffer 
R15 Address of User ID 


Figure 13-4. TPUT Parameter Registers 
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For the TGET macro, the registers must be formatted as shown in Figure 13-5. 


Reserved Buffer Size 


Address of Your Input Buffer 


Figure 13-5. TGET Parameter Registers 


Flags/Flag! 

One Byte 

OS sua: Always set to 0 for TPUT. 

eer Always set to 1 for TGET. 

LOA shee No user ID. 

5) eee Register 15 contains address of user ID. 

fe, | ame HIGHP processing is requested. 

gollcs egdue LOWP processing is requested. 

eh “ways WAIT processing is requested. 

seed? sont: NOWAIT processing is requested. 

nar, Oies NOHOLD processing is requested. 
1 


a HOLD processing is requested. 
0.. NOBREAK processing is requested. 
ob BREAK processing is requested. 
..00 EDIT processing is requested. 

01 ASIS processing is requested. 

..10 CONTROL processing is requested. 
i FULLSCR processing is requested. 


13-14 TSO/E Guide to Writing a TMP or a CP 


C 


If you use the execute form of the TPUT macro, the coded parameters expand 
into the parameter list shown in Figure 13-6. 


General 
Register 1 


+ 
+4 
Address of Your Output Buffer 


Flag s 
Reserved 


ec 


Figure 13-6. Parameter List Expansion for the Execute Form of TPUT 


If you use the standard form of the TPUT macro, you can code your parameters 
using registers or symbols. In this case, the TPUT macro expands to load the 
parameters into registers 0, 1, and 15 in the format illustrated in Figure 13-4. 


If you use the list form of the TPUT macro, the coded parameters expand into 
the parameter list shown in Figure 13-7. 


+0 
Address Space ID (ASID-TPUT only) Output Buffer Size 


Address of Your Output Buffer 


Address of User ID 


Reserved 


Figure 13-7. Parameter List Expansion for the List Form of TPUT 
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If you use the execute form of the TPG macro, the coded parameters expand into 
the parameter list shown in Figure 13-8. ) 


General 
Register 1 


+0 
Address Space 1D (ASID-TPUT only) Output Buffer Size 
+4 
Address of Your Output Buffer 


Address of User ID 
Flag 2 e 
(x'80") eser ved 


; 


Figure 13-8. Parameter List Expansion for the Execute Form of TPG 


If you use the list form of the TPG macro, the coded parameters expand into the 
parameter list shown in Figure 13-9. 


+ 
+4 
Address of Your Output Buffer 


Figure 13-9. Parameter List Expansion for the List Form of TPG 


For Figure 13-6-Figure 13-9, Flagl is the same as that for Flags in Figure 13-4 > 
and Figure 13-5. Flag2 is X‘01’ for the NOEDIT option and X‘02’ for the TPG Jd 
macro. 
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In Figure 13-10, Flags is the same as that for Flags in Figure 13-4 and 
Figure 13-5. 


If you use the standard, list, or execute form of the TGET macro, the coded 
parameters expand into the parameter list shown in Figure 13-10. 


Reserved Input Buffer Size 


F lags Address of Your Input Buffer 


Execute and Standard Form 


Reserved Input Buffer Size 


pe Address of Your Input Buffer 


List Form 


Figure 13-10. Parameter List Expansion for the Standard, List, and Execute Forms of TGET 


Coding Examples of TGET and TPUT Macro Instructions 


The following coding examples show different ways to use the TGET and TPUT 
macro instructions. 


Examples of TPUT and TGET Using the Default Values 


Figure 13-11 shows a TPUT and a TGET macro instruction. They both use the 
default values; that is, the TPUT macro instruction defaults to EDIT, WAIT, 
NOHOLD, and NOBREAK, and the TGET macro instruction defaults to EDIT 
and WAIT. 
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Figure 13-11. Coding Example: TPUT and TGET Macro Instructions Using the Default Values 


The program issuing the TGET macro instruction is not given control until a line 
of data is returned. The default value is WAIT. If less than 130 characters are 
entered, the input buffer is padded with blanks. The default is EDIT. Remember 
that the actual length of the data in the input buffer is returned in register 1. 
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Example of TPUT Macro Instruction -- Buffer Address and Buffer Length in Registers 


In the coding example shown in Figure 13-12 the output message buffer address 
and length are loaded into registers, and those registers coded as operands in the 
TPUT macro instruction. 


You might want to do this when, for example, the TPUT macro instruction is 
issued in a subroutine which receives, as parameters, a pointer to the message and 
the message length. 
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Figure 13-12. Coding Example: TPUT Macro Instruction Buffer Address and Buffer Length in Registers 
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Example of the TGET Macro Instruction -- Register Format 


Figure 13-13 shows the code necessary to issue a register format TGET macro Jo 
instruction. The buffer length, buffer address, and the option flags are loaded 

into registers zero and one. Note that the flag byte in register one is set to binary 
10000001, indicating that this is a TGET macro instruction requesting ASIS 

processing. This means that only minimal editing is performed on the input line. 
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Figure 13-13. Coding Example: TGET Macro Instruction Register Format 
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Chapter 14. Using Terminal Control Macro Instructions 


The following macro instructions allow a command processor to control terminal 
functions and attributes. 


Macro 
Instruction 


GTDEVSIZ 
GTSIZE 
GTTERM 
RTAUTOPT 
SPAUTOPT 
STATTN 
STAUTOCP 
STAUTOLN 
STBREAK 
STCC 
STCLEAR 
STCOM 
STFSMODE 
STLINENO 
STSIZE 
STTIMEOU 
STTMPMD 
STTRAN 
TCLEARQ 


Function 


Get device size 

Get terminal] line size 

Get terminal attributes 

Restart automatic line numbering or character prompting 
Stop automatic line numbering or character prompting 
Set attention simulation 

Start automatic character prompting 

Set automatic line numbering 

Set break 

Specify line-deletion and character-deletion characters 
Set display clear character string 

Set interterminal communication 

Set full-screen mode 

Set line number 

Set terminal line size 

Set timeout feature 

Set terminal display manager options 

Set character translation 

Clear buffers 


Some of the terminal control macro instructions may be safely coded in a 
user-written command processor. They are: 


GTDEVSIZ 
GTSIZE 
GTTERM 
RTAUTOPT 
SPAUTOPT 
STAUTOCP 
STAUTOLN 
STFSMODE 
STLINENO 
STTMPMD 
STSIZE 
TCLEARQ 


The other macro instructions are intended for system use and are not 
recommended for inclusion in user-written command processors. These macros 
are used in the IBM-supplied PROFILE and TERMINAL commands. 
Inappropriate use of the following macros can cause terminal errors: 


STATTN 
STBREAK 
STCC 
STCLEAR 
STCOM 
STTIMEOU 
STTRAN 
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Except for the GTSIZE, RTAUTOPT, SPAUTOPT, and STAUTOCP macros, all 
terminal control macros must be issued in 24-bit addressing mode. Note that all 
services invoked by the terminal control macros execute in 24-bit addressing 
mode. 


GTDEVSIZ -- Get Device Size 


Use the GTDEVSIZ macro instruction to determine the current logical line size 
and the number of lines of a user’s terminal. This macro returns both values 
regardless of the terminal type (that is, display or non-display). See the 
description of the GTSIZE macro, which you can use to obtain the screen length 
for display stations only. 


When GTDEVSIZ is issued in a time-sharing environment, the logical line size of 
the user’s terminal (that is, the maximum number of characters per line) is 
returned in register 1. The logical screen length (that is, the number of lines per 
display) is returned in register 0. If there is no maximum number of lines, register 
0 contains all zeros. 


The GTDEVSIZ macro is applicable only in a VTAM time-sharing environment. 
It is ignored if VTAM is not active when the macro instruction is issued. 


Figure 14-1 shows the format of the GTDEVSIZ macro instruction. 


Figure 14-1. The GTDEVSIZ Macro Instruction 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. The contents of registers 0 and 1 are described above. 
04 Parameter specified to the SVC. No parameter should be specified. 


GTSIZE -- Get Terminal Line Size 


Use the GTSIZE macro instruction to determine the current logical line size of 
the user’s terminal. When GTSIZE is executed in the background, it will return a 
line size of 132 characters and a screen size of 0 lines. If the terminal is a display 
station, use the GISIZE macro instruction to determine the size of the display 
screen. See the description of the GTDEVSIZ macro, which you can use to 
obtain the screen length for both display and non-display stations. 


When the GTSIZE macro instruction is issued in a time sharing environment, the 
logical line size of the user’s terminal (that is, the maximum number of characters 
per line) is returned in register 1. If the terminal is a display station, the line size 
is returned in register 1 and the screen length (that is, the maximum number of 
lines per display) is returned in register 0. If the terminal is an LU1 device type, 
register 0 will contain all zeros. The GTSIZE macro instruction is ignored if TSO 
is not active when the macro instruction is issued. 
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Figure 14-2 shows the format of the GTSIZE macro instruction. 


Figure 14-2. The GTSIZE Macro Instruction 


When contro! is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. The contents of registers 0 and 1 are described above. 
04 Parameter specified to the SVC. No parameter should be specified. 


GTTERM -- Get Terminal Attributes 


Use the GTTERM macro instruction to determine the primary (default) and the 
alternate screen sizes for a 3270 display terminal. Use the ERASE/WRITE 
command (X‘F5’) to erase the screen, to set the screen size mode to primary 
mode, and optionally to write data to the screen. Use the ERASE/WRITE 
ALTERNATE command (X°‘7E’) to erase the screen, to set the screen size mode 
to the alternate mode, and optionally to write data to the screen. Figure 14-3 
shows the format of the GTTERM macro instruction. 


symbol | GTTERM| PRMSZE=addr [,ALTSZE=addr] haul | L | 


(E,ctraddr) 
[, ATTRIB=addr } 


Figure 14-3. The GITERM Macro Instruction 


PRMSZE = addr 
Specifies the address of a 2-byte area into which GTTERM returns the 
primary row value in the high-order byte and the primary column value in 
the low-order byte. 


ALTSZE= addr 
Specifies the address of a 2-byte area into which GITERM returns the 
alternate row value in the high-order byte and the alternate column value in 
the low-order byte. 


ATTRIB = addr 
Specifies the address of a 1-word field into which GTTERM returns 
terminal attributes. The contents of this field are described below: 


Byte Bits Values Meaning 


0-2 Reserved 
3 0-5 Reserved 
6 The device supports EBCDIC code. 


7 The Read Partition (Query) is not supported. 


0 

| The device supports ASCII code. 

0 

1 The Read Partition (Query) is supported. 


Note: If ATTRIB is specified, you do not have to code PRMSZE or 
ALTSZE. 
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Indicates the form of the GITTERM macro instruction. 


L 
Specifies the list form. 


(E,ctrladdr) 
Specifies the execute form and the address of the list form. 


If you use the list form of the GTTERM macro, the coded parameters expand 
into the parameter list shown in Figure 14-4. 


Address of halfword to receive primary screen size 


Address of halfword to receive alternate screen size 


Address of word to receive Device Query supported flag 


Figure 14-4. Parameter List Expansion for the List Form of GTTERM 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

08 Terminal in use is not a display terminal. 

0C Required PRMSZE parameter was not specified. 


RTAUTOPT -- Restart Automatic Line Numbering or Character Prompting 


Use the RTAUTOPT macro instruction to restart either the automatic line 
numbering feature or the automatic character prompting feature. (The feature 
was suspended when the terminal user caused an attention interruption or entered 
a null line of input.) Since only one of these features can be used at a time, the 
restarted feature is the one that was suspended. (See the STAUTOLN macro 
instruction for a description of the automatic line numbering feature and the 
STAUTOCP macro instruction for a description of the automatic character 
prompting feature.) 


When this macro instruction is used to restart automatic line numbering, the first 
line number assigned after line numbering 1s restarted is the same line number 
that would have been assigned to the next line of terminal input if automatic line 
numbering had not been suspended. 


If the application program is creating a line numbered data set, use of the 
STAUTOLN macro to specify the starting number is recommended when 
restarting automatic line numbering. This will insure that the application’s 
numbers are still in synchronization with the system’s. 


The RTAUTOPT macro instruction is used only in a time sharing environment. 


If you issue this macro when TSO is not active or when you are running under 
Session Manager, it is ignored. 
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Figure 14-5 shows the format of the RTAUTOPT macro instruction. 


Figure 14-5. The RTAUTOPT Macro Instruction 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. Either automatic line numbering or automatic character prompting has 
been restarted. 

04 Parameter specified to the SVC. No parameter should be specified. 

08 Invalid request. Either automatic line numbering or automatic character prompting 


was never started or never suspended, or an SPAUTOPT macro instruction has been 
issued to stop automatic line numbering or automatic character prompting. 


SPAUTOPT -- Stop Automatic Line Numbering or Character Prompting 


Use the SPAUTOPT macro instruction to stop either the automatic line 
numbering feature or the automatic character prompting feature. Since only one 
of these features can be used at a time, the active feature is the feature that is 
stopped. (See the STAUTOLN macro instruction for a description of the 
automatic line numbering feature, and the STAUTOCP macro instruction for a 
description of the automatic character prompting feature.) 


The system can suspend automatic prompting when the terminal user causes an 
attention interruption or enters a null line of input. This macro should then be 
issued by the application program in its attention exit, or as the result of a zero 
length input line received via TGET. When stopped by the SPAUTOPT macro, 
prompting cannot be restarted by use of the RTAUTOPT macro. Prompting 
must be restarted by the STAUTOLN or STAUTOCP macro. 


The SPAUTOPT macro instruction is used only in a time sharing environment. If 
you issue this macro when TSO is not active or when you are running under 


Session Manager, it is ignored. 


Figure 14-6 shows the format of the SPAUTOPT macro instruction. 


Figure 14-6. The SPAUTOPT Macro Instruction 
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When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. Either automatic line numbering or automatic character prompting has 
been stopped. 

04 Parameter specified to the SVC. No parameter should be specified. 

08 Invalid request. Either automatic line numbering or automatic character prompting 


was never started. 
STATTN -- Set Attention Simulation 


Use the STATTN macro instruction to specify how a terminal user can interrupt 
the execution of his program without using an attention key. The TERMINAL 
command issues the STATTN macro when the terminal user requests that 
simulated attention be set up. 


When the STATTN macro instruction assigns a value to an operand, that value 
remains in effect until another STATTN macro instruction assigns a new value to 
the operand, or until the terminal user logs off. Issuing the STATTN macro 
instruction without specifying any operands results in a NOP instruction. 


The STATTN macro instruction is used only in a time sharing environment with 
terminals that use TSO through TCAM. It is ignored if TSO is not active when 
the macro instruction is issued. 


Figure 14-7 shows the format of the STATTN macro instruction. Each of the 
operands is explained following the figure. If an operand is not specified, its 
current status is not changed. 


[symbol] STATIN | LINES= Jinteger | sad aera | 


0 


| , LNPUT= Jaddress | 
0 


0 


Figure 14-7. The STATTN Macro Instruction 


LINES = 
Indicates the output line count (if any) that determines when a terminal user 
can interrupt the execution of his program. 


integer 
Specifies an integer from 1 through 255. This integer indicates the 
number of consecutive lines of output that can be directed to the 
terminal before the keyboard will unlock to let the terminal user 
interrupt the execution of his program. 
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Indicates that output line count will not be used to determine when 
the terminal user can interrupt the execution of his program. 


The LINES operand applies only to terminals that are not display 
stations. However, the display user may cause a simulated attention 
interruption at the bottom of the screen (that is, after every 6, 12, or 
15 lines of consecutive output, depending on screen size). 


TENS = 
Indicates whether or not locked keyboard time will be used to determine 
when a terminal user can interrupt the execution of his program. 


integer 
Specifies an integer from 1 through 255. This integer indicates the 
tens of seconds (that is, from 10 to 2550 seconds) of locked keyboard 
time that can elapse before the keyboard will unlock to let the 
terminal user interrupt the execution of his program. 


Indicates that locked keyboard time will not be used to determine 
when the terminal user can interrupt the execution of his program. 


INPUT = 
Indicates whether or not a character string will be used to determine when a 
terminal user can interrupt the execution of his program. 


address 
Specifies the address of a character string from one to four EBCDIC 
characters long, left-justified and padded to the right with blanks if 
less than four characters long. When this character string is 
encountered as the only data in a line, input processing is interrupted 
to let the program take an attention exit. (See the description of the 
STAX macro instruction.) This string will not be recognized if it is 
preceded by any other character, including line delete or character 
delete control characters. 


Indicates that no character string will be used to determine when the 
terminal user can interrupt the execution of his program. 


When control is returned to the user, register 15 will contain the following return 
code: 


Hexadecimal 

Code Meaning 

00 Successful 

08 Invalid terminal type. This macro instruction should not be issued for terminals that 


use VTAM. 
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STAUTOCP -- Start Automatic Character Prompting 


Use the STAUTOCP macro instruction to start automatic character prompting. J 
Automatic character prompting signals the terminal user when the system is ready 

to accept input from the terminal. This signal consists of putting out at the 

terminal either an underscore and a backspace or a period and a carriage return, 

depending on the type of terminal being used. The STAUTOCP macro has no 

effect with a display station, since the terminal user is always prompted for input 

by the start-of-message symbol. 


This macro instruction can be used to have the system automatically prompt the 
user for input. It is used, for example, by the INPUT subcommand of EDIT. 


Once started, automatic prompting is handled as follows: When the system has 
received a line of input, it immediately sends back to the terminal the next 
character prompt. If the program should send output while automatic prompting 
is in effect, the prompt will be repeated after all output has been set to the 
terminal. For example: 


line of input 
OUTPUT MSG FROM PROGRAM 


Automatic prompting is designed to be used by a program operating in input 
mode (that is, issuing successive TGET macros). 


The system suspends automatic prompting when the terminal user causes an 

attention interruption or when he enters a null (nonprinting) line of input. The 

application program then takes appropriate action in an attention exit routine, or 

after receiving a zero length input via the TGET macro instruction. The J 
application program can stop the prompting or line numbering function via 

SPAUTOPT, or restart the function via STAUTOCP. 


The STAUTOCP macro instruction is used only in a time sharing environment. 
It is ignored if issued by a batch task or if you are running under Session 


Manager. 


Figure 14-8 shows the format of the STAUTOCP macro instruction. 


[symbol] STAUTOCP 


Figure 14-8. The STAUTOCP Macro Instruction 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Parameter specified to the SVC. No parameter should be specified. 
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C 


STAUTOLN -- Start Automatic Line Numbering 


Use the STAUTOLN macro instruction to start automatic line numbering. 
Automatic line numbering displays a line number at the beginning of each line. 


This macro instruction can be used to have the system automatically prompt the 
user for input. It is used, for example, by the INPUT subcommand of the EDIT 
command. 


Once started, automatic line numbering is handled as follows: when the system 
has received a line of input, it immediately sends back to the terminal the next 
line number. If the program should send output while automatic line numbering 
is in effect, the line number will be repeated after all output has been set to the 
terminal. For example: 


00030 line of input 
00040 OUTPUT MSG FROM PROGRAM 
00040 


Automatic line numbering is designed to be used by a program operating in input 
mode (that is, issuing successive TGET macros). 


The system displays a new line number for each line of input received. The 
current line number maintained by the system is decremented appropriately 
whenever the input queue is cleared by a TCLEARQ macro or as the result of an 
attention interruption. The application program is responsible for numbering the 
lines independently, if it is creating a line numbered data set. The system line 
number is not available to the application program. 


The system suspends automatic line numbering when the terminal user causes an 
attention interruption or when he enters a null (nonprinting) line of input. The 
application program then takes appropriate action in an attention exit routine, or 
after receiving a zero length input via the TGET macro instruction. The 
application program can stop the line numbering function via SPAUTOPT, or 
restart the function via STAUTOLN or RTAUTOPT. You should use 
STAUTOLN rather than RTAUTOPT to restart automatic line numbering if the 
application program is numbering the input lines it receives. This choice will 
insure that the program’s numbers are still in synchronization with the system’s 
numbers. 


The STAUTOLN macro instruction is used only in a time sharing environment. 
It is ignored if issued by a batch task or if you are running under Session 


Manager. 


Figure 14-9 shows the format of the STAUTOLN macro instruction. Each of the 
operands is explained following the figure. 


[symbol] S=address, I=address 


Figure 14-9. The STAUTOLN Macro Instruction 
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STBREAK -- Set Break 


indicates the address of a fullword that contains the number to be assigned 
to the first line of terminal input. This number can be any integer from 0 J 
through 99,999,999. 


indicates the address of a fullword that contains the increment value to be 
used when assigning line numbers to lines of terminal input. This number 
can be any integer from 0 through 99,999,999. 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. A line number will be printed out at the beginning of each line of input. 
04 Invalid parameter specified - values out of range. 


Use the STBREAK macro instruction to indicate whether the transmit interrupt 
feature on an IBM 1050, 2741, 3270, 3767, or 3770 terminal will be used or 
suppressed. The transmit interrupt feature lets terminal output processing 
interrupt terminal input processing. 


The TERMINAL command issues this macro when the terminal user specifies the 
BREAK or NOBREAK operand of the command. 


The transmit interrupt feature is a special feature on 1050 and 2741 terminals; it is J 
a standard feature on the 3767, 3770, and 3270 display terminals. Specifying 

STBREAK YES for a 1050 without the transmit interrupt feature could result in 

loss of output or a permanent error at the terminal. 


When the transmit interrupt feature is being used by the system, the terminal user 
can enter the next line while the previous one is being processed. Al1.33/35 
Teletypes and IBM 3270, 3767, and 3770 terminals are handled this way. 1050s 
and 2741s that have been defined in the TCAM message control program as 
having the transmit interrupt feature will be handled this way (unless STBREAK 
NO is specified). 


Note: For 2741s, 3767s, 3770s, TWX, and WTTY devices supported by VTAM, 
the keyboard will remain unlocked when STBREAK NO is specified. 


When the feature is in use, terminal handling of input and output is as follows: if 
no output is available for the terminal, and if there are sufficient TSO terminal 
buffers available, the keyboard will be unlocked to allow the user to enter input. 
If the user’s program generates output (TPUT) before he has started to enter 
data, the read operation is halted and the break (transmit interrupt) feature can 
be used to lock the keyboard and condition the communications line to transmit 
output. If the user has already started to type when the TPUT is issued, the 
output will not be sent until he has finished that line of input. If, however, the 
TPUT had specified the BREAKIN option, the output message would interrupt 
any input in progress. If the application does not issue a TCLEARQ macro to 
flush the input buffer queue, the interrupted input from a 1050 or a 2741 terminal ~J 
will be printed out again after the output is sent, to let the user continue to type 
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from the point where he had been interrupted. If the application does not issue a 
TCLEARQ macro to flush the input buffer queue, the interrupted input from a 
3767, 3270, or a 3770 terminal is received by the application program but is not 
printed at the terminal. 


When the transmit interrupt feature is not being used by the system, a 1050 or 
2741 terminal keyboard is unlocked only after the user’s program has issued a 
TGET request for input. (A 3270, 3767, or 3770 terminal keyboard’s normal 
state is unlocked.) In this mode of operation, the terminal user cannot type ahead 
of his program. A TPUT with the BREAKIN option cannot interrupt input. 

The output will not be sent until the terminal user has completed entering his 
current input line. All display stations are handled in this way. All 1050s and 
2741s that have been defined in the TCAM message control program as not 
having the transmit interrupt feature will be handled this way. 


The STBREAK macro instruction is used only in a time sharing environment. It 
is ignored if TSO is not active when the macro instruction is issued. 


Figure 14-10 shows the format of the STBREAK macro instruction. 


[symbol] | STBREAK | 


Figure 14-10. The STBREAK Macro Instruction 


YES 
Indicates that the transmit interrupt feature will be used. YES is the 
default. 


NO 
Indicates that the transmit interrupt feature not be used. 


When control is returned to the user, register 15 will contain one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid terminal type. This macro instruction should be issued only for the IBM 1050, 


2741, 3270, 3767, or 3770 terminal. 
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STCC -- Specify Terminal Control Characters 


Use the STCC macro instruction to specify what control characters will be used to J 
delete a character or a line of terminal input. 


The PROFILE command issues this macro when a terminal user requests a new 
line or character deletion character. The PROFILE command also causes the 
newly defined characters to be included in the user’s profile in the user attribute 
data set (UADS). Each time the user logs on, the terminal monitor program will 
issue the STCC macro, specifying the characters in the UADS at the start of the 
session. If the terminal user does not use the PROFILE command to change the 
line or character-deletion characters, the system-supplied defaults are always used. 
A description follows. 


When the line-delete control character specified in the STCC macro instruction is 
encountered within a line of terminal input, the line control character and all the 
preceding characters in that line are deleted. When the character-delete control 
character specified in the STCC macro instruction is encountered within a line of 
terminal input, the character delete control character and the character 
immediately preceding it are deleted from the line. 


When the user is logging on, he can delete a line or character by using the 
system-supplied defaults. The defaults, according to type of terminal, are as 


follows: 

Type of Terminal Desired Action Key(s) to be Pressed 

1050 and 2741 line deletion or Attention key and backspace 
character deletion ) 

33/35 Teletypel line deletion or CTRL and X key (hex‘18’), back arrow (<-), or 


character deletion underscore (_), depending on keyboard. (Either 
key results in hex ‘6D’.) 


3767/3770 line deletion or Attention key and backspace 
character deletion 


No defaults are defined for the display stations, because the terminal user can use 
cursor control keys more effectively to delete characters or lines before the input 
is transmitted to the system. 


The STCC macro instruction is valid in a time sharing environment with 
terminals (other than LU_TI devices) that use TSO with the exception that 
ATTN/NATN is not supported in a VTAM environment. STCC is ignored if 
TSO is not active when the macro instruction is issued. 


Figure 14-11 shows the format of the STCC macro instruction; each of the 
operands is explained following the figure. 


[symbol] | STCC ATTN ,LD=} X'n' 
NATN Cre? 


Figure 14-11. The STCC Macro Instruction 


l Trademark of the Teletype Corporation. 
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ATTN 
When this operand is in effect, depressing the ATTENTION key after 
having typed data will only delete the current line. System response is !D. 
Automatic prompting is not turned off. The ATTENTION key can then be 
depressed again, without typing any input, to interrupt the program and 
turn off prompting. When this operand is not in effect, the attention key 
will both delete a line of terminal input and interrupt the execution of the 
user’s program. System response is! or SI. 


NATN 
Indicates that the attention key will not be used to delete a line of terminal 
input. 


LD= 
Indicates what character will be used for the line delete control character: 


X‘n’ 
Where n is the hexadecimal representation of any EBCDIC character 
on the terminal keyboard, except the new line (NL) and carrier return 
(CR) control characters. If X‘00’ is specified, the previously used 
line-delete control character is retained. If X‘FF’ is specified, no 
character will be used for the line-delete control character. If an 
invalid character is specified, that character is rejected and no 
character is used to delete a line of terminal input. 


C*e’ 
Where c is the character representation of any EBCDIC character on 
the terminal keyboard. 


CD= 
Indicates what character will be used for the character delete control 
character: 


X‘n’ 
Where n is the hexadecimal representation of any EBCDIC character 
on the terminal keyboard except the new line (NL) and carrier return 
(CR) control characters. If X‘Q0’ is specified, the previously used 
character delete control character is retained. If X‘FF’ is specified, no 
character will be used for the character delete control character. If an 
invalid character is specified, that character is rejected and no 
character is used to delete a character from a line of terminal input. 


Where c is the character representation of any EBCDIC character on 
the terminal keyboard. 


When control is returned to the user, the low-order byte of register 0 contains the 
former line delete control character. If X‘FF’ appears in the low-order byte of 
register 0, there is no former line delete control character. If X‘80’ appears in the 
high-order byte of register 0, ATTN was in effect for line deletion prior to the 
issuance of the STCC macro. 


The low-order byte of register | contains the former character delete control 


character. If X‘FF’ appears in the low-order byte of register 1, there is no former 
character delete control character. 
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Register 15 contains one of the following return codes: 


Hexadecimal J 


Code Meaning 

00 Successful. 

04 Invalid parameters specified to the SVC. 

08 Invalid request. Specified character does not appear on the terminal keyboard or 


ATTN was specified for a terminal that does not have an attention key. 


0c Invalid terminal type. 
STCLEAR -- Set Display Clear Character String 


Use the STCLEAR macro instruction to specify the character string that will be 
used to request that a 2260 or 2265 display station screen be erased. The 
TERMINAL command issues this macro when the user specifies the character 
string he wants. 


The STCLEAR macro instruction is used only in a time sharing environment. It 
is ignored if TSO is not active when the macro instruction is issued. 


Figure 14-12 shows the format of the STCLEAR macro instruction. Each of the 
operands is explained following the figure. 


[symbol] STRING= Jaddress 
2 


Figure 14-12. The STCLEAR Macro Instruction 


STRING = 
Indicates the address of a one- to four-character string that will be used to 
request that the display station screen be erased. This character string must 
be left-justified and padded on the right with blanks, if necessary. If 0 is 
specified, no character string will be used to erase the screen. 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter. 

08 Invalid terminal type. The terminal is not a display station. 


STCOM -- Set Inter-Terminal Communication 


Use the STCOM macro instruction to specify whether or not a terminal will 

accept messages from other terminals or low priority messages from the system 

operator. High priority operator messages are always sent to the terminal. The 

PROFILE command issues this macro when the user specifies the INTERCOM 

or NOINTERCOM operand of the command. J 
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The STCOM macro instruction is used only in a time sharing environment. It is 
ignored if TSO is not active when the macro instruction is issued. 


Figure 14-13 shows the format of the STCOM macro instruction. 


[symbol] | STCOM YES 
NO 


Figure 14-13. The STCOQM Macro Instruction 


YES 
Indicates that the terminal will accept messages from other terminals. If 
neither YES nor NO is specified, YES is assumed. 


NO 
Indicates that the terminal will not accept messages from other terminals. 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 


STFSMODE -- Set Full-Screen Mode 


Use the STFSMODE macro instruction under VTAM to specify whether an IBM 
3270 display terminal 1s to operate in full-screen mode. Operating in full-screen 
mode provides screen protection by preventing the screen from being overlaid by 
non-full-screen messages, and allowing the terminal user to read non-full screen 
messages before they are overlaid by full-screen messages. If full-screen mode is 
set off, full-screen TPUT requests (that is, TPUT requests that specify the 
FULLSCR operand) can result in certain problems at the terminal. A message 
not expected by the terminal user or the command processor, such as a broadcast 
message or password request, might not be noticed by the terminal user and might 
be quickly overlayed by a full-screen display. An unexpected message might 
overlay part of a full-screen display, which could result in invalid input to the 
command processor. 


In general, the STFSMODE macro instruction can be used only in a VTAM 
time-sharing environment and is ignored if issued when VTAM is not active. 
However, if the TSO Extensions session manager is installed and a TCAM 
time-sharing environment is active, the STFSMODE macro instruction can be 
issued, but only the session manager can use it. 


See Appendix B for additional information about the use of the STFSMODE 
macro and the full-screen environment. 
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Figure 14-14 shows the format of the STFSMODE macro instruction. 


[symbol] | STFSMODE | | ON ||,INITIAL=YES | |,NOEDIT=YES| [,RSHWKEY=n] |,PARTION=YES 
OFF ||, INITIAL=NO ||,NOEDIT=NO _PARTION=NO 


Figure 14-14. The STFSMODE Macro Instruction 


ON 


OFF 


Indicates that full-screen mode is in operation. If neither ON nor OFF is 
specified, ON is assumed. When a terminal operating in full-screen mode is 
to receive a non-full-screen message (TPUT without FULLSCR), the display 
screen is cleared, the alarm is sounded (if the Audible Alarm special feature 
is installed), and the message is displayed on the screen. If several such 
messages occur one after the other, the screen is cleared once, the alarm is 
sounded, and the messages are displayed in sequence. When the next 
full-screen TPUT message (TPUT with FULLSCR) is issued by the 
application, the terminal user will be required to acknowledge the messages 
on the screen before the TPUT FULLSCR can be displayed. Three 
asterisks (***) displayed at the current line indicate that acknowledgement is 
required. To continue, the user must press the ENTER key. 


Indicates that full-screen mode is not in operation. When a terminal that is 
not operating in full-screen mode receives a message, the RSHWKEY is 
reset to the default, and the message is sent to the terminal according to the 
options specified in the TPUT macro, possibly overlaying the current screen 
contents. 


INITIAL= YES 


Indicates that this is the first time during the execution of a command 
processor that the command processor has entered full-screen mode. This 
operand prevents the first TPUT FULLSCR issued by the command 
processor from forcing a paging condition when the last transaction at the 
terminal was input. For example, after a user logs on and the READY 
message is displayed and the user types in the name of a command 
processor, a paging condition is not forced if INITIAL= YES was specified. 
INITIAL= YES is ignored if OFF is specified. 


INITIAL=NO 


Indicates that forced paging is to occur normally whenever a TPUT with 
FULLSCR follows a TPUT without FULLSCR. If neither INITIAL= YES 
nor INITIAL=NO is specified, INITIAL = NO is assumed. 


NOEDIT = YES 


Indicates that input from the terminal will be added to the input queue 
without being modified, regardless of the options specified on the TGET 
macro instruction. 


TSO/VTAM supports 3270 extended data stream functions via TGET in 
unedited input mode and TPUT NOEDIT. For more information about 
TPUT NOEDIT, refer to “The TPUT Macro Instruction -- Writing a Line 
to the Terminal” on page 13-1. 
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J 


NOEDIT =NO 
Indicates that input from the terminal will be handled according to the 
options specified on the TGET macro instruction before it is added to the 
input queue. If neither NOEDIT=NO nor NOEDIT= YES is specified, 
NOEDIT = NO is assumed. 


RSHWKEY 
Specifies as a decimal digit the program function (PF) key to be used as the 
reshow key. If RSHWKEY is not specified, the default value for the PA2 
key (X‘6E’) is used. 


PARTION= YES 
Indicates to TSO/VTAM that partitions are being used and the buffer 
address of the terminal screen is either a 14 or a 16-bit address. 


PARTION=NO 
Indicates to TSO/VTAM that partitions are not being used and the buffer 
address of the terminal screen is a 12-bit address. 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid terminal type. This macro instruction is valid only for IBM 3270 display 


terminals that use VTAM. 


STLINENO -- Set Line Number 


Use the STLINENO macro instruction under VTAM to specify the number of the 
screen line on an IBM 3270 display terminal on which the next non-full-screen 
message should appear. (A non-full-screen message results from issuing a TPUT 
macro instruction without the FULLSCR operand.) The STLINENO macro 
instruction may also be used to specify whether the 3270 terminal is to operate in 
full-screen mode. 


In general, the STLINENO macro instruction can be used only in a VTAM 
time-sharing environment and is ignored if issued when VTAM is not active. 
However, if the TSO Extensions session manager is installed and a TCAM 
time-sharing environment is active, the STLINENO macro instruction can be 
issued, but only the session manager can use it. 


See Appendix B for additional information about the use of the STLINENO 
macro and the full-screen environment. 
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Figure 14-15 shows the format of the STLINENO macro instruction. 


[symbol] | STLINENO LINE=number Foc | 


LINELOC=address| | ,MODE=OFF 


Figure 14-15. The STLINENO Macro Instruction 


LINE= 
Specifies in decimal the line number on which the next non-full-screen 
message 1s to appear. The line number must be a value from 1 to n where n 
is the maximum number of lines allowed for the terminal in use. Either the 
actual line number or a register (2-12, enclosed in parentheses) containing 
the line number in the low-order byte may be specified. 


LINELOC = 
Specifies the address of a fullword whose low-order byte contains the 
number of the screen line on which the next non-full-screen message is to 
appear. Either an actual address (RX-type) or a register (2-12, enclosed in 
parentheses) containing the address may be specified. 


MODE = 
Specifies whether full-screen mode is to be set ON or OFF. If MODE is 
not specified, MODE = OFF is assumed. 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid terminal type. This macro instruction is valid only for IBM 3270 display 
terminals that use VTAM. 

0c The line number specified was 0 or it was greater than the maximum number of lines 


allowed for the terminal in use. 


STSIZE -- Set Terminal Line Size 


Use the STSIZE macro instruction to set the logical line size of the time sharing 
terminal. 


If the terminal is a display station, the STSIZE macro instruction is used to set 
the screen size. The STSIZE macro changes only the logical screen size of a 
terminal. In non-full-screen processing, the logical and physical screen sizes are 
the same. However, in full-screen processing they are not necessarily the same 
and when they are not the same, this macro does not change the physical screen 
size of the terminal. Full-screen applications can change the physical screen size 
using the appropriate WRITE command. 


The TERMINAL command issues this macro instruction when the user specifies 
the LINESIZE or SCRSIZE operands of the command. 
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The STSIZE macro instruction is used only in a time sharing environment. If you 
issue this macro when TSO is not active or when you are running under Session 
Manager, it is ignored. 


Figure 14-16 shows the format of the STSIZE macro instruction. Each of the 
operands is explained following the figure. 


[symbol] | STSIZE SIZE=number , LINE=number 
SIZELOC=address|| ,LINELOC=address 


Figure 14-16. The STSIZE Macro Instruction 


SIZE 
Specify the logical line size of the terminal in characters. If the logical line 
size requested is greater than the physical line size of the terminal, the last 
character in the line may be repeatedly typed over. Specifying a size greater 
than 255 gives unpredictable results. 


SIZELOC 
Specify the address of a word containing the logical line size of the terminal 
in characters. 


LINE 
Specify the number of lines that can appear on the screen of a display 
station terminal. 


LINELOC 
Specify the address of a word containing the number of lines that can 
appear on the screen of a display station terminal. 


Note: If the terminal is a display station, either the LINE or LINELOC operand 
must be specified. If the terminal is not a display station, neither operand should 
be specified. 


Defaults by terminal type are as follows: 
Terminal Type Line Size, Number of Lines, or Screen Size 


2741 120 

1050 120 

33/35 Teletype2 72 

2260,2265 12x80, 12x40, 6x40, 15x64 - as specified by the installation in the TCAM message 
control program. 

3270 12x40 or 24x80 

3767 132 

3770 132 


2 Trademark of the Teletype Corporation. 
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When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal J 


Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid LINE, LINELOC, SIZE, or SIZELOC operand, as follows: 


1. The LINE or LINELOC operand was specified for any terminal except a display 
station. (An operand value of zero is not an error, and has the same effect as 
omitting the operand.) 


2. The LINE or LINELOC operand was omitted, or specified as zero, for a display 
station. 


3. The SIZE or SIZELOC operand was omitted, or specified as zero, for any 
terminal type. 


0C The dimensions specified for a display station do not correspond to known existing 
screen size. Incorrect screen management can result. 


STTIMEOU -- Set Time Out Feature 


Use the STTIMEOU macro instruction to specify whether the 1050 terminal has 
the optional text time out suppression feature. The macro instruction allows 
1050s, with or without the feature, to call in via the same switched line, with any 
1050 being handled initially as if it did not have the feature. 


A 1050 without the text time out suppression feature operates as follows: When 

the PROCEED light is on and the keyboard is unlocked, the terminal will time 

out; that is, the keyboard will lock if the user does not type input for | 
approximately 20 seconds. The system subsequently responds to the time out by J 
restoring the keyboard so that the user may continue. The user can prevent the 

time out by periodically pressing the SHIFT key. 


A 1050 with the text time out suppression feature operates as follows: The 
keyboard does not lock if the user does not type input within 20 seconds. The 
system can therefore use the read inhibit channel command, which does not time 
out within 28 seconds, in contrast to the read channel command that does time 
out. (Note: If the system is directed to use the read inhibit channel command for 
a 1050 that does time out, the terminal may be locked out of the system.) 


Until the STTIMEOU macro instruction is issued, 1050 terminals are handled as 
per the definition provided in the TCAM message control program. If the 
currently connected terminal has the text time out suppression feature, 
STTIMEOU NO can be issued to direct the system to use read inhibit rather than 
read channel commands. (STTIMEOU NO should not be issued for a 1050 that 
does not have the text time out suppression feature. This specification could 
cause the terminal to be locked out of the system.) 


The TERMINAL command processor issues the STTIMEOU macro instruction 
when the user specifies the TIME OUT or NOTIMEOUT operand of the 
TERMINAL command. The STTIMEOU macro instruction will remain in effect 
until the user logs off. 


The STTIMEOU macro instruction should be issued only when an IBM 1050 


terminal is being used. Terminals which are equivalent to the one explicitly ) 
supported may also function satisfactorily. The customer is responsible for 
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establishing equivalency. IBM assumes no responsibility for the impact that any 
changes to the IBM-supplied products or programs may have on such terminals. 


The STTIMEOU macro instruction is used only in a time sharing environment. 
It is ignored if TSO is not active when the macro instruction is issued. 


Figure 14-17 shows the format of the STTIMEOU macro instruction. 


Figure 14-17. The STTIMEOU Macro Instruction 


YES 
Indicates that IBM 1050 terminal does time out. It does not have the text 
time out suppression feature. If the operand is omitted, the default is YES. 


NO 
Indicates that the IBM 1050 terminal does not time out. The 1050 does 
have the text time out suppression feature. 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 

08 Invalid terminal type. This macro instruction applies to the IBM 1050 terminal only. 


STTMPMD -- Set Terminal Display Manager Options 


Use the STTMPMD macro instruction to specify whether a Display Terminal 
Manager is active or whether the PAI and CLEAR key indications are to be 
passed through to the application program. 


The STTMPMD macro instruction is issued only in a time-sharing environment. 
It is ignored if issued for a non-TSO task. The STTMPMD macro is valid for 
display terminals operating in both the TCAM and VTAM environments. 


Figure 14-18 shows the format of the STTMPMD instruction. Each of the 
operands is explained following the figure. 


[symbol] | STTMPMD ON , KEYS=| NO 
OFF ALL 


Figure 14-18. The STTMPMD Macro Instruction 
ON 


Indicates that a Display Terminal Manager is in control. If neither ON nor 
OFF is specified, ON is the default. 
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OFF 
Indicates that a Display Terminal Manager is not in control. 


KEYS =NO 
Indicates that the PAl and CLEAR key indications are not to be returned 
to the application program. This is the default if the KEYS operand is 
omitted. 


KEYS = ALL 
Indicates that the PAl and CLEAR key indications are to be returned to 
the application program. 


When control is returned to the user, register 15 contains one of the following 


return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified. 

08 Invalid terminal type. This is not a display terminal. 


STTRAN -— Set Character Translation 


Use the STTRAN macro instruction to initiate the use of user-specified 
translation tables, to modify specific character translations in active translation 
tables, to remove character modifications made to user-specified translation 
tables, and to terminate the use of user-specified translation tables. Translation 
tables allow characters entered at the terminal to be interpreted as other 
characters when they are received by TSO, and characters sent by TSO to be 
interpreted as other characters when they are received at the terminal. 


The TERMINAL command issues this macro instruction when a terminal user 
specifies the TRAN, NOTRAN, CHAR, or NOCHAR operand of the command. 


Translation tables are built and used in pairs: one for input and one for output. 
Each pair is a control section consisting of a fullword containing the address of 
the output table, followed by a 256-byte EBCDIC table for translating the 
inbound characters, followed by a 256-byte EBCDIC table for translating the 
outbound characters. Each character in an input table must have a counterpart in 
its companion output table, and the characters must have the same relative 
position in both tables. Refer to SPL: TSO/E User Exits and Modifications 
Volume 2 for instructions on building translation tables. 


A translation table translates inbound data after the system translates the line 
code to EBCDIC characters. A translation table translates outbound data before 
the system translates EBCDIC characters to line code. 


The STTRAN macro instruction is used only in a VTAM time-sharing 


environment. It is ignored if VTAM is not active when the macro instruction is 
issued. 
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Figure 14-19 shows the format of the STTRAN macro instruction. Each of the 
operands is explained following the figure. 


7 


Figure 14-19. The STTRAN Macro Instruction 


NOTRAN 


Pa address ,NAME=address | 
oan address ,SCHAR=address 


NOCHAR , NAME= pdaress 


a ctrl addr) 


TABLE = address 
Specifies the address of a pair of user-written translation tables. 


NAME = address 
Specifies the address of an 8-byte area containing an EBCDIC character 
string. (The string is left-justified and padded to the right with blanks if it is 
less than eight characters long.) The character string consists of the name of 
a member in a load module that contains user-written translation tables. 


When NAME is used with NOCHAR, the STTRAN macro instruction 
causes the command processor to store the member name in the 8-byte area. 


NOTRAN 
Specifies that the use of user-written translation tables be discontinued. 


TCHAR = address 
Specifies the address of a 1-byte area containing the EBCDIC representation 
of a character as it appears at the terminal. 


SCHAR = address 
Specifies the address of a 1-byte area containing the EBCDIC representation 
of a character as it appears to the system. 


NOCHAR 
Specifies that current TCHAR and SCHAR values are no longer in effect. 


MF = 
Indicates the form of the STTRAN macro instruction. 


L 
Specifies the list form. 


(E,ctrl addr) 
Specifies the execute form and the address of the list form. 
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When control is returned to the user, register 15 contains one of the following 


return codes: 

Hexadecimal 

Code Meaning 

00 Successful. 

04 NOTRAN or NOCHAR was specified but translation was not in effect. 

08 TABLE or NOCHAR was specified but the NAME operand did not specify an 
address. 

0c Internal error - unidentifiable flag set in input register 0. 


TCLEARQ -- Clear Buffers 


TCLEARQ enables the user to throw away “typed ahead” input or unsent output. 
This clearing of the buffers lets the command processor resynchronize with the 
terminal user. 


For example, when a command processor analyzes the specified operands in a line 
of input and discovers missing or invalid parameters, it issues a TCLEARQ 
INPUT before sending a prompting message to the user. This ensures that the 
command processor will receive a line of input entered after the terminal user has 
seen the prompting message. 


When the TCLEARQ macro instruction is issued to clear the input buffers, all the 
input that has been entered at the terminal, but has not yet been processed by the 
foreground Job, is purged. To ensure synchronization, the terminal keyboard on a 
TCAM terminal is locked until the next TGET macro is issued. Keyboards on 
terminals that use VTAM do not lock. 


When the TCLEARQ macro instruction is issued to clear the output buffers, all 
the output that has been processed by the foreground job but not yet displayed at 


the terminal is purged. 


The TCLEARQ macro instruction is used only in a time sharing environment. It 
is ignored if TSO is not active when the macro instruction is issued. 


The TCLEARQ macro instruction is written as follows: 


Figure 14-20 shows the format of the TCLEARQ macro instruction; each of the 
operands is described following the figure. 


[symbol] | TCLEARQ INPUT 
OUTPUT 


Figure 14-20. The TCLEARQ Macro Instruction 


INPUT 
Indicates that all input currently in the terminal’s input buffer queue will be 
lost, including the input line currently being entered, if any. If neither 
INPUT nor OUTPUT is specified, INPUT is assumed. 
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OUTPUT 
Indicates that all the output for this terminal that is currently in the 
terminal’s output buffer queue will be purged, except for output messages 
that have begun to appear at the terminal, or messages from other terminals 
or the system operator. (Such messages are sent via the TPUT TJID macro 
instruction.) 


When control is returned to the user, register 15 contains one of the following 
return codes: 


Hexadecimal 

Code Meaning 

00 Successful. 

04 Invalid parameter specified to the SVC. 
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Chapter 15. Command Scan and Parse -- Determining the Validity 


of Commands 


Sequence of Operations 


If you write your own command processors to run under TSO, you need a 
method of determining whether any command name or subcommand name 
entering the system is valid, and whether the operands following the command are 
syntactically correct. Command scan and parse are the two service routines 
provided with TSO that perform these functions. 


Command scan searches the command buffer for a valid command name. The 
parse service routine scans the command buffer for operands. 


In general, command scan is invoked by a terminal monitor program and the 
parse service routine is invoked by a command processor. Command scan may 
also be invoked by any command processors that process subcommands. 


Both of these service routines receive control via the CALLTSSR or LINK 
macro. Their entry points are: 


Service Routine Entry Point 


Command Scan IKJSCAN 
Parse IKJPARS 


If your TMP or command processor uses command scan and/or the parse service 
routine, the sequence of operations is as follows: 


1. Your terminal monitor program or command processor gets a line of input 
which may contain a command and its operands. 


2. Your terminal monitor program or command processor uses the LINK macro 
or the CALLTSSR macro to invoke command scan (IKJSCAN) and passes it 
a parameter list containing, among other things, the address of the command 
buffer. 


3. Command scan searches the buffer for a command name, checks the syntax 
of the command name (if you request it to), updates the command buffer 
offset field to point to the command operands (if any), and returns control to 
the calling program. 


4. The calling program receives the address of the command name and gives 
control to the appropriate command processor or subcommand processor. 
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5. The command processor invokes the parse service routine (IKJPARS) via the 
CALLTSSR or LINK macro, and passes it parameter lists containing, among 
other things, the syntactical structure of the command operands, and the J 
address of the command buffer. 


6. The parse service routine scans the buffer for operands, builds a list 
describing the operands found, and returns control to the calling program. 


7. The command processor processes the command according to the operands 
received. 


8. When the command processor terminates, it returns control to the terminal 
monitor program and the sequence is repeated. 


The following sections discuss: 


e Acceptance of double-byte character set data 
e Using the command scan service routine 
e Using the parse service routine 


Acceptance of Double-Byte Character Set Data (MVS/XA Only) 


In MVS/XA only, command scan and parse accept double-byte character set 

(DBCS) strings in addition to EBCDIC character strings. The shift-out character 

(X‘OE’) indicates a change from EBCDIC to DBCS; the shift-in character (X‘0F’) 
indicates the reverse. Each double-byte character requires a double-byte J 
representation so that valid DBCS strings contain an even number of bytes. With 

the exception of blank, which is X‘4040’, each byte has a value between X‘41’ and 

X‘FE’. If the DBCS string contains an invalid character, parse replaces it with 

X°4195’. 


Double-byte characters can appear in comments and certain types of strings of 
user data. If the programming language you are using supports DBCS data, 
default values can also contain valid DBCS strings. DBCS strings that appear 
where they are not accepted could cause an error condition. The types of user 
strings that can contain DBCS data along with the associated parse macro and 
parameter follows: 


Self delimiting string (STRING parameter of IKJPOSIT) 

Quoted string (QSTRING parameter of IKJPOSIT) 

Parenthesized string (PSTRING parameter of IKJPOSIT) 

Value string (VALUE parameter of IKJPOSIT) 

Quoted character constant (CONSTANT parameter of IKJTERM) 
Quoted character string (CHAR or HEX parameter of IKJIDENT). 


Parse does not accept DBCS strings in prompting mode. In addition, you cannot 

use DBCS strings in quoted data set names, quoted passwords for data sets, or 

quoted passwords for user IDs because MVS does not accept DBCS strings in 

those cases. However, the parse macro, IKJPOSIT, treats X‘OE’ and X‘OF’ as 

DBCS delimiters in quoted data set names (DSNAME and DSTHING 

parameters), quoted passwords for data sets (DSNAME and DSTHING J 
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parameters), and quoted passwords for user IDs (USERID and UID2PSWD 
parameters). 


Check all hexadecimal data that you pass to parse to be sure that X‘OE’ and 
X‘OF’ represent the shift-out and shift-in characters when appropriate. 
Previously, parse treated those characters simply as hexadecimal data. Now, 
when used in the strings mentioned earlier in this topic, parse treats them as 
DBCS delimiters. Therefore, change X‘OE’ and X‘OF’ to some other values if 
they do not represent the shift-out and shift-in characters and you are passing 
them through the parse service. 


Using the Command Scan Service Routine IKJSCAN) 


In general, a terminal monitor program links to command scan to verify 
command names. Command scan may also be invoked by the TEST program or 
by any command processors that process subcommands. It can also be used to 
scan the reply to a prompt message. 


Command scan examines a command in a command buffer and performs the 
following functions: 


l. 


2. 


It translates all lowercase characters in the command name to uppercase. 

If a valid parameter is present, it resets the offset to the number of text bytes 
preceding the first non-blank character in the operand field. If a valid 
operand is not present, the offset equals the length of the text portion of the 
buffer. 


It returns a pointer to the command name, the length of the command name, 
and a code explaining the results of its scan to the calling routine. 


It optionally checks the syntax of the command name. 


It recognizes an implicit EXEC command that has a percent sign as the first 
character. 


It has logic to handle leading blanks and embedded comments. 
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This topic discusses: 


Command name syntax ) 
The parameter list structure required by command scan 


The command scan parameter list 

Flags passed to command scan 

The command scan output area 

The operation of the command scan service routine 
The results of the command scan 

Return codes from command scan 


Command Name Syntax 
If you write your own command processor, and you intend to use the command 
scan service routine to check for a valid command name, your name must meet 
the following syntax requirements: 
e The first character must be an alphabetic or a national character. 
e@ The remaining characters must be alphameric. 
@ The length of the command name must not exceed eight characters. 


e The command delimiter must be a separator character. 


e@ The name should include one or more numerals. Since no IBM-supplied 
command names include numerals, your command name will be unique. ) 
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The Parameter List Structure Required by Command Scan 


Before invoking the command scan service routine via the CALLTSSR macro, 
you must create the parameter structure shown in Figure 15-1. You then place 
the address of the command scan parameter list (CSPL) into general register 1, set 
the flags in the flag word, and issue CALLTSSR specifying IKJSCAN, the 
command scan service routine. 


IKJSCAN may be invoked in either 24- or 31-bit addressing mode. IKJSCAN 
executes in 31-bit addressing mode and can be passed input that resides above or 
below 16 Mb in virtual storage. 


Flag Word 


~[ 


Command Scan Output Area 


Command Nome Pointer To be set by 


Command 


Command Buffer 


Command Buffer 


Ti [om | 
0 2 4 


Figure 15-1. The Parameter List Structure Passed to Command Scan 


The Command Scan Parameter List 


The command scan parameter list (CSPL) is a six-word parameter list containing 
addresses required by the command scan routine. In order to ensure the 
reenterability of the calling program, the CSPL should be built in subpool | in an 
area obtained by the calling program with the GETMAIN macro instruction. 
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The CSPL is defined by the IKJCSPL DSECT. Figure 15-2 shows the format of 
the command scan parameter list. 


Number 
of Bytes Contents or Meaning 


4 CSPLUPT The address of the user profile table. 
CSPLECT 
CSPLECB 


The address of the environment contro! table. 


The address of the command processor’s event control block. 
(Required if command scan is called by a command processor to scan a 
subcommand; zeros if command scan is called by the TMP.) 


The address of a fullword, obtained via the GETMAIN macro 
instruction by the routine linking to command scan, and located in 
subpool |. The first byte of the word pointed to contains flags set by 
the calling routine; the last three bytes are reserved. 


CSPLFLG 


CSPLOA The address of an 8-byte command scan output area, located in 

subpool |. The output area is obtained by the calling routine via a 
GETMAIN macro instruction. It is filled in by the command scan 
service routine before it returns control to the calling routine. (See 


Figure 15-1.) 
The address of the command buffer. 


CSPLCBUF 


Figure 15-2. The Command Scan Parameter List 


Flags Passed to Command Scan 


The flag word built in subpool | and pointed to by the fourth word of the CSPL 
is obtained and freed by the calling routine. Only the first byte of the field is used 
by the command scan service routine; the remaining three bytes are reserved. Set 
the flag byte before linking to the command scan routine to indicate whether or 
not you want the command to be syntax checked. The flag byte has the following 
meanings: 


X‘00’ Syntax check the command name. 
X‘80’ ~=Do not syntax check the command name. 


The Command Scan Output Area 


The command scan service routine returns the results of its scan to the calling 
program by filling in a two-word command scan output area (CSOA). The 
CSOA must be obtained and freed by the calling program. It must be located in 
subpool 1 and its address stored into the fifth word of the command scan 
parameter list before your program links to IKJSCAN. 


The CSOA is defined by the IKJCSOA DSECT. Figure 15-3 shows the format 
of the command scan output area. 


Number 
of Bytes Contents or Meaning 


CSOACNM | The address of the command name if the command name is present and 
valid. Zero otherwise. 


CSOALNM Length of the command name if the command name is present and 


valid. Zero otherwise. 


CSOAFLG A flag field. Command scan sets these flags to indicate the results of its 


scan. See Figure 15-5. 


Reserved. 


Figure 15-3. The Command Scan Output Area 
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C 


The Operation of the Command Scan Service Routine 


If you set the flags field in the flag word to X‘80’ (do not syntax check the 
command name) the command scan service routine scans the buffer to determine 
if it contains a question mark or a command. The first character in the command 
buffer is checked for a question mark whether or not syntax checking is requested. 
If it is a question mark, no further scanning is done. If it is not a question mark, 
the command name is considered to begin at the first non-separator character 
found, and end at the first command delimiter character found. See Figure 15-4 
for a list of the separator characters. 


Command scan translates any lowercase letters in the command name to 
uppercase, fills the command scan output area, updates the command buffer 
offset field, and returns to the calling program. 


If you have requested syntax checking (X‘00’ in the flag field of the flag word), 
the command name must meet the syntax requirements, as follows: 


The first character must be an alphabetic or a national character. 
The remaining characters must be alphameric. 

The length of the command name must not exceed eight characters. 
The command delimiter must be a separator character. 


If the flag field in the flag word is set to X‘00’ (syntax check the command) and 
the user enters a percent sign (%) as the first character of a command name, 
command scan will: 


e Turn on the CSOAEXEC flag to X‘04’. 


e Update the command name pointer to the next position following the percent 
sign. 


e Continue the scan. 


Figure 15-4 shows the various character types recognized by command scan and 
parse. Unless otherwise indicated, alphameric characters are: 


Alphabetic (A-Z) 


Numeric (0-9) 
National ($, #, @) 
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Comment 
Horizontal Tab 
Blank 

Comma 

Dollar Sign 
Number Sign 
At Sign 


Character Type 
Command ) 
Separator | National | Alphabetic | Numeric | Delimiter Delimiter | Special 
X 
xX 


Le 
Jj 


ZEPRQee’ os 
Po RN 


New line 

Period 

Left parenthesis 
Right parenthesis 
Ampersand 


*#*Q—"™" 


Asterisk 
Semicolon 

Minus sign, hyphen 
Slash 

Apostrophe 

Equal sign 

Cent sign 

Less than 

Greater than 

Plus sign 

Logical OR 
Exclamation point 
Logical NOT 
Percent sign 

Dash 

Question mark 
Colon 

Quotation Mark 
Shift-out! 
Shift-in! 

IThe shift-out and shift-in characters indicate the beginning and end of a string of double-byte character set data. (MVS/XA only) 


etal el nel elelels 


alelelalalelalalalololale 


Figure 15-4. Character Types Recognized by Command Scan and Parse 


Results of the Command Scan 


The command scan service routine scans the command buffer and returns the 
results of its scan to the calling routine by filling in the command scan output 
area, and by updating the offset field in the command buffer. Figure 15-5 shows 
the possible CSOA settings and command buffer offset settings upon return from 
the command scan service routine. 
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C 


Command Scan Output Area Command Buffer 


Length Fel 


The command name is valid and the Length of command name The first non-separator following the 
remainder of the buffer contains command name. 


non-separator characters 


The command name is valid and Length of command name The end of the buffer. 
there are no non-separator characters 


mark. 


The buffer is empty only separators. The end of the buffer. 


X‘08’ | The command name is syntactically Zero Unchanged. 
invalid. 

X‘04 =| The command is an implicit EXEC Length of command name The first non-separator following the 
command. command line. 


Figure 15-5. Return from Command Scan - CSOA and Command Buffer Settings 


Return Codes from Command Scan 


The command scan service routine returns the following codes in general register 
15 to the program that invoked it: 


Hexadecimal 

Code Meaning 

0 Command scan completed successfully. 

4 Command scan was passed invalid parameters. 


Using the Parse Service Routine (IKJPARS) 


The parse service routine checks the syntax of command operands. To prepare 
for this, the command processor creates a parameter control list (PCL) -- a 
description of permissible operands, default values, text to be used when 
prompting, and, if present, the address of a validity checking subroutine. 


The command processor invokes the parse service routine via the CALLTSSR or 
LINK macro, passing it a parse parameter list (PPL) which contains the address 
of the PCL. The parse service routine scans and checks each operand against the 
entries (called PCEs: parameter control entries) in the PCL. In turn, the parse 
service routine builds and returns results of the scan to the command processor in 
a parameter descriptor list (PDL), whose entries contain pointers to data set 
names, indications of specified options, or pointers to the subfields entered with 
the command operands. 


The command processor uses the IKJPARMD DSECT to refer to the PDL. The 
command processor specifies the IKJPARMD DSECT at the time it issues the 
parse macro instructions to build the PCL. The labels used by the command 
processor on the various parse macro instructions become the symbolic addresses 
of the fields in the IKJPARMD DSECT. 


IKJPARS may be invoked in either 24- or 31-bit addressing mode. IKJPARS 
executes in 31-bit addressing mode and can accept input above or below 16 Mb in 
virtual storage. 
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Figure 15-6 depicts a command processor’s use of the parse macro instructions, 
the parse service routine, and the IKJPARMD DSECT. ) 


Command Buffer 


toh oma] cement | amt | Pte? | et | 
0 2 4 


Command Processor @) CALLTSSR/LINK to Parse Parse Service Routine 
q) Issues Parse macro G3) Compares PCE's to 


instructions to build parameters in the 
a PCL describing Command Buffer. 
valid parameters 

e label] Macro 

e label2 Macro 

e label3 Macro 


These macro 
instructions also 
create the 
IKJPARMD DSECT. 


(4) Builds the PDL. 
IKJPARMD 


DSECT 

Mabel 7 

(label a i. ) 
Habel = 

ee 


(5) Return to the Command Processor 


6) The Command 
Processor uses the 
IKJPARMD DSECT 
to access the various 
PDEs within the 
PDL. 


Figure 15-6. A Command Processor Using the Parse Service Routine 
The parse service routine support consists of the following: 
1. The following set of macro instructions: 
IKJPPL builds an IKJPPL DSECT which maps the parse parameter list. 


IKJPARM begins the parameter control list and establishes a symbolic 
reference for the parameter descriptor list. 


IKJPOSIT builds a parameter control entry. This PCE describes a positional 

parameter that contains delimiters recognized by the parse service routine, but ' 
not including the positional parameters described by the IKJTERM, J 
IKJOPER, IKJIDENT, or IKJRSVWD macro instructions. 
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IKJIDENT also builds a parameter control entry; however, this PCE 
describes a positional parameter that does not depend upon a particular 
delimiter. 


IKJKEYWD builds a parameter control entry that describes a keyword 
parameter. 


IKJNAME describes the possible names that may be entered for a keyword 
or a reserved parameter. 


IKJTERM builds a parameter control entry. This PCE describes a positional 
parameter that may be a constant, statement number, or variable. 


IKJOPER builds a parameter control entry that describes an expression. An 
expression consists of three parts; two operands and an operator in the form: 


(operand! operator operand2) 


IKJRSVWD builds a parameter control entry. This PCE may be used with 
the IKJTERM macro instruction to describe a reserved word constant, with 
the IKJOPER macro instruction to describe the operator of an expression, or 
by itself to describe a reserved word parameter. 


IKJSUBF indicates the beginning of a keyword subfield description. 
IKJENDP indicates the end of the PCL. 

IKJRLSA releases any virtual storage (allocated by the parse service routine) 
that remains after the parse service routine has returned control to the 
command processor. 

A program that checks the syntax of the command operands within the 


command buffer against the PCL and builds a PDL containing the results of 
the syntax check. 


The parse service routine also provides the following services which may be 
selected by the calling routine: 


It translates the command operands to uppercase. 
It substitutes default values for missing operands. 
It prompts the user at the terminal for missing positional parameters. 


It passes control to an exit, supplied by the calling routine, to do further 
checking on a positional parameter. 


It inserts implied keywords. 


It appends user-supplied second level messages to prompting messages. 
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This section describes: 


Command parameter syntax 

Using the parse macro instructions to define command syntax 
The parse macro instructions 

Passing control to the parse service routine 

Formats of the PDEs returned by the parse service routine 
Additional facilities provided by the parse service routine 

An example of using the parse service routine 

Return codes from the parse service routine 


Command Parameter Syntax 


Positional Parameters 


If you write your own command processors, and you intend to use the parse 
service routine to determine which operands have been entered following the 
command name, your command parameters must adhere to the syntactical 
structure described in this section. 


Command parameters must be separated from one another by one or more of the 
separator characters: blank, tab, comma, or a comment (see Figure 15-4). The 
command parameters end either at the end of a logical line (carrier return), or at 
a semicolon. If the command parameters end with a semicolon, and other 
characters are entered after the semicolon but before the end of the logical line, 
the parse service routine ignores that portion of the line that follows the 
semicolon. The parse service routine returns no message to indicate this 
condition. 


There are two types of command parameters recognized by the parse service 
routine: 


1. Positional parameters 
2. Keyword parameters 


Positional parameters must be coded first in the parameter string, and they must 
be in a specific order. 


In general, the parse service routine considers a positional parameter to be missing 
if the first character of the parameter scanned is not the character expected. For 
instance, if a parameter is supposed to begin with a numeric character and the 
parse service routine finds an alphabetic character in that position, the numeric 
parameter is considered missing. The parse service routine then prompts for the 
missing parameter if it is required, substitutes a default value if one is available, 
or ignores the missing parameter if the parameter is optional. 


For the purpose of syntax checking, positional parameters are divided into 
parameters that include delimiters as part of their definition (delimiter-dependent 
parameters), and parameters that do not include delimiters as part of their 
definition (non-delimiter-dependent parameters). 
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Delimiter-Dependent Parameters: Those parameters that include delimiters as 
part of their definition are called delimiter-dependent parameters. The parse 
service routine recognizes the following delimiter-dependent parameter syntaxes 
shown in Figure 15-7. 


Macro Instruction Used to Describe Parameter 


DELIMITER 
STRING 

VALUE 

ADDRESS 

PSTRING IKJPOSIT 
USERID 

UID2PSWD 

DSNAME 

DSTHING 

QSTRING 

SPACE 

JOBNAME 


CONSTANT 
VARIABLE IKJTERM 
STATEMENT NUMBER 


EXPRESSION IKJOPER 
RESERVED WORD IKJRSVWD 


HEX 
CHAR IKJIDENT 
INTEG 


Figure 15-7. Delimiter-Dependent Parameters 


DELIMITER 
It may be any character other than an asterisk, left parenthesis, right 
parenthesis, semicolon, blank, comma, tab, carrier return, digit, shift-out 
character (X‘QE’), or shift-in character (X‘OF’). A self-defining delimiter 
character is represented in this discussion by the symbol #. The delimiter 
parameter is used only in conjunction with the string parameter. 


STRING 


A string is the group of characters between two alike self-defining delimiter 
characters, such as 


#string# 


or, the group of characters between a self-defining delimiter character and 
the end of a logical line, such as 


#string 


The same self-defining delimiter character can be used to delimit two 
contiguous strings, such as 


#string#string# 
or 
#string#string 
A null string, which indicates that a positional parameter has not been 


entered, is defined as two contiguous delimiters or a delimiter and the end 
of the logical line. If the missing string is a required parameter, the null 
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string must be entered as two contiguous delimiters. Note that a string 
received from a prompt or a default must not include the delimiters. See 
“Acceptance of Double-Byte Character Set Data (MVS/XA Only)” for 
information about using double-byte character set data in a self-delimiting 
string. 


VALUE 
A value consists of a character followed by a string enclosed in apostrophes, 
such as 


X‘string’ 


The character must be an alphabetic or national character. The string may 
be of any length and may consist of any combination of enterable 
characters. If the ending apostrophe is left off the string, the parse service 
routine assumes that the string ends at the end of the logical line. If the 
parse service routine encounters two successive apostrophes, it assumes them 
to be part of the string and continues to scan for a single ending 
apostrophe. The parse service routine always raises the character preceding 
the first apostrophe to uppercase. The value is considered missing if the 
first character is not an alphabetic or national character, or if the second 
character is not an apostrophe. See “Acceptance of Double-Byte Character 
Set Data (MVS/XA Only)” for information about using double-byte 
character set data in a value string. 


ADDRESS 
There are several forms of the ADDRESS parameter. 


Absolute address 
An absolute address consists of from one to six hexadecimal digits 
followed by a period, or, in extended mode, from one to eight 
hexadecimal digits followed by a period. An extended absolute 
address must not exceed the address represented by the hexadecimal 
value 7FFFFFFF. (For more information on extended addressing, 
see the description of the EXTENDED operand in “IKJPOSIT - 
Describing a Delimiter-Dependent Positional Parameter” below.) 


Relative address 
A relative address consists of from one to six hexadecimal digits 
preceded by a plus sign, or, in extended mode, from one to eight 
hexadecimal digits preceded by a plus sign. 


General register address 
A general register address consists of a decimal integer in the range 0 
to 15 followed by the letter R. R can be entered in either uppercase 
or lowercase. 


Floating-point register address 
A floating-point register address consists of an even decimal integer in 
the range 0 to 6 followed by the letter D (for double precision) or E 
(for single precision). The letter E or D can be entered in either 
uppercase or lowercase. 
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Symbolic address 
A symbolic address consists of any combination, up to 32 characters 
in length, of the alphameric characters and the break character. The 
first character must be either an alphabetic or a national character. 


Qualified address 
A qualified address has one of the following formats: 


. modulename.entryname.relative-address 
- modulename.entryname 
- modulename.entryname.symbolic-address 


.entryname.symbolic-address 
.entryname.relative-address 
.entryname 


e modulename - any combination of one to eight alphameric 
characters, of which the first is an alphabetic or national character 


® entryname - same syntax as a modulename, and always preceded 
by a period 


@ symbolic address - syntax as defined above, and always preceded 
by a period 


@ relative address - syntax as defined above, and always preceded by 
a period 


You may qualify symbolic or relative addresses to indicate that they 
apply to a particular module and CSECT as in formats 1-3. However, 
if the address applies to the currently active module, you do not have 
to specify modulename, as in formats 4-6. 


Indirect address 
An indirect address is an absolute, relative, symbolic, or general 
register address followed by from one to 255 indirection symbols. 
When the EXTENDED keyword is specified on the IKJPOSIT macro, 
the user may specify the 31-bit indirection symbol, ?. The 24-bit 
indirection symbol, %, may also be specified. If EXTENDED is not 
specified, the user is limited to using the 24-bit indirection symbol. 


Note: In the following examples, hash marks indicate that the byte is 
not used to determine the 24-bit address. 
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Figure 15-8 shows an example of an indirect address that is made up 
of a relative address with one level of 24-bit indirect addressing. 


+A% 
RELATIVE LOC +A 


LOC C2C 


Figure 15-8. Example of 24-Bit Indirect Addressing 
The number of indirection symbols following the address indicates the 
number of levels of indirect addressing. In Figure 15-8, the data is at 
the location pointed to by bits 0-24 of relative address + A. 
Figure 15-9 shows how the substitution of a 31-bit indirection symbol, 


?, changes the result of the resolution of an indirect address. The 
example assumes that EXTENDED has been specified on IKJPOSIT. 


| +A? 


RELATIVE LOC +A 


LOC 23000C2C 


Figure 15-9. Example of 31-Bit Indirect Addressing 
Figure 15-10 shows an example of an indirect address in which 24- 
and 31-bit indirection symbols are combined. The example assumes 
that EXTENDED has been specified on IKJPOSIT. 


In Figure 15-10, four levels of indirect addressing are processed to 
resolve the indirect address. 
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+A%22% 
Cc RELATIVE LOC +A 


LOC 100A094 


4 Figure 15-10. An Indirect Address with Mixed Indirection Symbols 
Address expression 
An address expression has one of two formats, depending on whether 


the EXTENDED keyword is specified on the IKJPOSIT macro. 


EXTENDED not specified: 


An address expression has the following format when EXTENDED 
has not been specified: 


e address - can be an absolute, symbolic, indirect, relative, or 
general register address. If a general register is specified, it must 
be followed by at least one indirection symbol. 


® expression value - a plus or minus displacement from an address 
in storage, consisting of from one to six decimal or hexadecimal 
digits 
— Decimal displacement is indicated by an “N” or “n” following 


the offset. The absence of an “N” or “n” indicates 
¢ hexadecimal displacement. 
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— There is no limit to the number of expression values in an 


address expression. ) 


@ Each expression value may be followed by from one to 255 
percent signs, one for each level of indirect addressing. 


For example, addr] + 124n, an address expression in decimal format, 
indicates a location 124 decimal bytes beyond addr]. Another 
example, addr2-AC, is an address expression in hexadecimal format 
and indicates a location 172 decimal bytes before addr2. 


The processing of an address expression, 12R%%+4N%, involving 
24-bit indirect addressing, is shown in Figure 15-11. The address in 
the expression is a general register address with two levels of indirect 
addressing. The result of the processing of this part of the address 
expression is location 1D0. The expression value indicates a 
displacement of four bytes beyond location 1D0 with one level of 
indirect addressing. The data, then, is at location 474. 


12R%%+4N% 


LOC 474 


Figure 15-11. An Address Expression with 24-Bit Indirect Addressing 


Note: Blanks are not allowed within any form of the address 
parameter. 
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EXTENDED specified: 


An address expression has the following format when EXTENDED 
has been specified: 


{+}expression —_ % | | 
2 Mecarss 


e address - can be an absolute, symbolic, indirect, relative, or 
general register address. If a general register is specified, it must 
be followed by at least one indirection symbol. 


® expression value - a plus or minus displacement from an address 
in storage, consisting of a one to ten digit decimal number, or a 
one to eight digit hexadecimal number. 


— Decimal displacement is indicated by an “N” or “n” following 


the offset. The absence of an “N” or “n” indicates 
hexadecimal displacement. 


— There is no limit to the number of expression values in an 
address expression. 


e Each expression value may be followed by from one to 255 
indirection symbols (including any valid combination of question 


marks and percent signs), one for each level of indirect addressing. 


The processing of an address expression involving both 24- and 31-bit 
indirect addressing is shown in Figure 15-12. 


Chapter 15. Command Scan and Parse -- Determining the Validity of Commands 15-19 


TR?%4+4N%2% 


R7 
Baa 


LOC 728 


CANES 


y LOC AC4 


abetee 
=e 
Z| 
LOC 784 


See 


LOC 3001288 


ZA 22 | 79} 20 


LOC 37920 
DATA 


Figure 15-12. An Address Expression with Mixed Indirection Symbols 


PSTRING 
A parenthesized string is a string of characters enclosed within a set of 
parentheses, such as: 


(string) 


The string may consist of any combination of characters of any length, with 
one restriction; if it includes parentheses, they must be balanced. The 
enclosing right parenthesis of a PSTRING can be omitted if the string ends 
at the end of a logical line. 


A null PSTRING is defined as a left parenthesis followed by either a right 
parenthesis or the end of a logical line. See “Acceptance of Double-Byte 
Character Set Data (MVS/XA Only)” for information about using 
double-byte character set data in a parenthesized string. 
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USERID 
A user ID consists of an identification optionally followed by a slash and a 
password. The format is: 


identification[/password] 


identification 
Can be any combination of alphameric characters up to seven 
characters in length, the first of which must be an alphabetic or 
national character. 


password 
Can be any combination of alphameric characters up to eight 
characters in length. If delimiters are used, the password must be 
enclosed in quotes. If quotes are to be used in the password, two 
quotes must be entered consecutively. One of them will be eliminated 
by the parse service routine. 


Separators may be inserted between the identification and the slash, and 
between the slash and the password. 


If just the identification is entered, the parse service routine does not prompt 
for a password. If the identification is entered followed by a slash and no 
password, the parse service routine prompts for a password by executing a 
PUTGET macro instruction specifying bypass mode. The terminal user can 
reply to a prompt for password by entering either a password or a null line. 
If the user enters a null line, the parse service routine builds the PDE and 
leaves the respective password field zero. 


UIDZPSWD 
A user ID consists of an identification optionally followed by two 
passwords. The delimiter between the three values is a slash. The format is: 


identification[/password1[/password2] ] 


identification 
Can be any combination of alphameric characters up to seven 
characters in length, the first of which must be an alphabetic or 
national character. 


password! 
Can be any combination of alphameric characters up to eight 
characters in length. If delimiters are used, the password must be 
enclosed in quotes. If quotes are to be used in the password, two 
quotes must be entered consecutively. One of them will be eliminated 
by the parse service routine. 


password2 
Same as password]. 


IKJPOSIT generates a variable length parameter control entry (PCE). 
Within the PCE, a field contains a hexadecimal number indicating the type 
of positional operand described by the PCE. For UID2PSWD, the 
hexadecimal number is C. 


Chapter 15. Command Scan and Parse -- Determining the Validity of Commands 15-21 


DSNAME 
The data set name parameter has three possible formats: 


dsname [ (membername)] [/password] 
[dsname] (membername) [password] 


'dsname [ (membername)] ' [/password] 


dsname 
May be either a qualified or an unqualified name. 


An unqualified name is any combination of alphameric characters up 
to eight characters in length, the first character of which must be an 
alphabetic or national character. 


A qualified name is made up of several unqualified names, each 
unqualified name separated by a period. A qualified name, including 
the periods, may be up to 44 characters in length. 


membername 
One to eight alphameric characters, the first of which must be an 
alphabetic or a national character. 


Note: The parse service routine considers the entire dsname parameter 
missing if the first character scanned is not an apostrophe, an alphabetic 
character, a national character, or a left parenthesis. If the VOLSER option 
is specified, the first character may be numeric. 


If it is numeric, only six characters are accepted for VOLSER. VOLSER is 
valid only for DSNAME or DSTHING. If USERID is specified, the parse 
service routine will prefix all data set names not entered in quotes with the 
user identification (from the UPT). 


If the slash and the password are not entered, the parse service routine does 
not prompt for the password. If the slash is entered and not the password, 
the parse service routine prompts for the password by executing a PUTGET 
macro instruction specifying bypass mode; that is, the terminal user’s reply 
will not print at the terminal. 


DSTHING 
A DSTHING is a dsname parameter as previously defined except that an 
asterisk can be substituted for an unqualified name or for each qualifier of a 
qualified name. The parse service routine processes the asterisk as if it were 
a dsname. The asterisk is used to indicate that all data sets at that 
particular level are considered. 


Note: If the first character of a dsname is an asterisk, the parse service 
routine will not prefix the USERID. 
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QSTRING 
A quoted string is a string of characters enclosed within apostrophes, such 
as: 


‘string’ 


The string can consist of any length combination of characters, with one 
restriction: if the user wishes to enter apostrophes within the string, two 
successive apostrophes must be entered for each single apostrophe desired; 
one of the apostrophes is removed by the parse service routine. 


The ending apostrophe is not required if the string ends at the end of the 
logical line. 


A null quoted string is defined as two contiguous apostrophes or an 
apostrophe at the end of the logical line. See “Acceptance of Double-Byte 
Character Set Data (MVS/XA Only)” for information about using 
double-byte character set data in a quoted string. 


SPACE 
Space is a special purpose parameter; it allows a string parameter that 
directly follows a command name to be entered without a preceding 
self-defining delimiter character. The space parameter must always be 
followed by a string parameter. If the delimiter of the command name is a 
tab, the tab is the first character of the string. The string always ends at the 
end of the logical line. 


JOBNAME 
The jobname may have an optional job identifier. Each job identifier is a 
maximum of eight alphameric characters of which the first is alphabetic or 
national. There is no separator character between the jobname and job 
identifier. The syntax is jobname (jobid). 


CONSTANT 
There are several forms of the constant parameter. 


Fixed-point numeric literal - Consists of a string of digits (0 through 9) 
preceded optionally by a sign (+ or -), such as: 


+ 1234.43 
This literal may contain a decimal point anywhere in the string except as the 
rightmost character. The total number of digits cannot exceed 18. 
Embedded blanks are not allowed. 
Floating-point numeric literal - Takes the following form: 

+ 1234.56E + 10 
This literal is a string of digits (0 through 9) preceded optionally by a sign 
(+ or -) and must contain a decimal point. This is immediately followed by 


the letter E and then a string of digits (0 through 9) preceded optionally by 
a sign (+ or -). Embedded blanks are not allowed. The string of digits 
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preceding the letter E cannot be greater than 16 and the string following E 
cannot be greater than 2. 


Non-numeric literal - Consists of a string of characters from the EBCDIC 
character set, excluding the apostrophe, and enclosed in apostrophes, 
entered as: 


“numbers (1234567890) and letters are ok’ 


The length of the string excluding apostrophes may be from | to 120 
characters in length. 


Figurative constant - Is one of a set of reserved words supplied by the caller 
of the parse service routine such as: 


test123 


A figurative constant consists of a string of characters up to 255 in length. 
Embedded blanks are not allowed. All characters of the EBCDIC character 
set are allowed except the blank, comma, tab, semicolon, and carrier return, 
however, the first parameter must be alphabetic. See “Acceptance of 
Double-Byte Character Set Data (MVS/XA Only)” for information about 
using double-byte character set data in a quoted character constant. 


VARIABLE 
The following is the form of the variable parameter. 


IN 
(subscript) 


— OF _ | 


Program-id 
Consists of the first eight characters of a program identifier followed 
by a period. The first character must be alphabetic (A through Z) and 
the remaining characters must be alphabetic or numeric (0 through 9): 


Data-name 
Consists of a maximum of 30 characters of the set: 


A through Z (alphabetic) 
0 through 9 (numeric) 
- (hyphen) 

typically entered as: 


mydataset-123 


The data-name cannot begin or end with a hyphen and must contain 
at least one alphabetic character. 


hereS5.mydataset-123 
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Qualification 
Is applied by placing after a data-name one or more data-names 
preceded by the qualifiers IN or OF, entered as: 
mydataset-123 of yourdataset-456 


The number of qualifiers that can be entered for a data-name is 
limited to 255. 


Subscript 
Consists of a data-name with subscripts enclosed in parentheses 
following the data-name entered as: 


yourdataset-456 (mydataset-123) 


A separator between the data-name and the subscript is optional. 
Subscripts are a list of constants or variables. 


The number of subscripts that can be entered for a data-name is 
limited to 3, entered as: 


here55 (abc def h1 5) 


A separator character between subscripts is required. 


STATEMENT NUMBER 


The following is the form of a statement number: 


[program id.]line number[.verb number] 
An example 1s: 

here.23.7 
where: 


Program id 
Consists of the first eight characters of a program identifier followed 
by a period. The first character must be alphabetic (A through Z) and 
the remaining characters must be alphameric (A through Z or 0 
through 9). 


Line number 
Consists of a string of digits (0 through 9) and cannot exceed a length 
of 6 digits. 


Verb number 
Consists of one digit (0 through 9) that is preceded by a period. 


Embedded blanks are not allowed in a statement number. 
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EXPRESSION 
An expression takes the form: 


(operandl operator operand2) 


The operator in the expression shows a relationship between the operands, 
such as: 


(abc equals 123) 


An expression must be enclosed in parentheses. An expression is defined by 
the IKJOPER macro. The operands are defined by the IKJTERM macro, 
and the operator by the IKJRSVWD macro instruction. 


RESERVED WORD 
Has three uses depending on the presence or absence of operands on the 
IKJRSVWD macro instruction. The uses are: 


@ When used with the RSVWD keyword of the IKJTERM macro 
instruction, the IKJRSVWD macro identifies the beginning of a list of 
reserved words, any one of which can be entered as a constant. 


@ When used with the RSVWD keyword of the IKJOPER macro 
instruction, the IKJRSVWD macro identifies the beginning of a list of 
reserved words, any one of which can be an operator in an expression. 


@ When used by itself, the IKJRSVWD macro instruction defines a 
positional reserved word parameter. 


Note: The IKJRSVWD macro instruction is followed by a list of 
IKJNAME macros that contain all of the possible reserved words used as 
figurative constants or operators. 


The HEX, CHAR, and INTEG operands on the IKJIDENT macro describe 
delimiter positional parameters. 


e HEX - indicates that any quantity of the form X‘nn’, ‘ABC’ (quoted 
string), or any nonquoted character string in which case a separator or 
delimiter indicates the end, will be accepted as valid data. See 
“Acceptance of Double-Byte Character Set Data (MVS/XA Only)” for 
information about using double-byte character set data in a quoted 
string of characters. 


e CHAR - indicates that any data in the form of a quoted or nonquoted 
string will be accepted as valid data. See “Acceptance of Double-Byte 
Character Set Data (MVS/XA Only)” for information about using 
double-byte character set data in a quoted string of characters. 


e INTEG - indicates that any numeric character in the following form will 
be converted by the parse service routine to its appropriate binary value. 


(X‘nn’) - where n is a valid hexadecimal digit(A-F,0-9), maximum of 8. 
(B‘mm’) - where m is a valid binary bit (0-1), maximum of 32. 


dddddd - decimal digits (0-9), maximum of 10. 


Note: The maximum decimal value for INTEG is 2147843647. 
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Positional Parameters Not Dependent on Delimiters: A positional parameter that 
is not dependent on delimiters is passed as a character string with restrictions on 
the beginning character, additional characters, and length. These restrictions are 
passed to the parse service routine as operands on the IKJIDENT macro 
instruction. 


The parse service routine recognizes the following character types as the beginning 
character and additional characters of a non-delimiter-dependent positional 
parameter: 


ALPHA 
Indicates an alphabetic or national character. 


NUMERIC 
Indicates a number (0-9). 


ALPHANUM 
Indicates an alphabetic or national character or a number. 


ANY 
Indicates that the character to be expected can be any character other than 
a blank, comma, tab, semicolon, or carrier return. A right parenthesis must, 
however, be balanced by a left parenthesis. 


NONATABC 
Indicates an alphabetic character only is accepted. (No national characters.) 


NONATNUM 
Indicates numbers and alphabetic characters are accepted.(No national 
characters.) 


An asterisk can be entered in place of any positional parameter that is not 
dependent on delimiters. 


Entering Positional Parameters as Lists of Ranges: You may want to have some 
positional parameters of your command entered in the form of a list, a range, or a 
list of ranges. The macro instructions that describe positional parameters to the 
parse service routine, IKJPOSIT, IKJTERM and IKJIDENT, provide a LIST 
and a RANGE operand. If coded in the macro instruction, they indicate that the 
positional parameters expected can be in the form of a list or a range. 


LIST 
Indicates to the parse service routine that one or more of the same type of 
positional parameters may be entered enclosed in parentheses as follows: 


(positional-parameter positional-parameter...) 
If one or more of the items contained in the list are to be entered enclosed 


in parentheses, both the left and the right parenthesis must be included for 
each of those items. 
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The following positional parameter types may be used in the form of a list: 


VALUE 

ADDRESS 

USERID 

UID2PSWD 

DSNAME 

DSTHING 

JOBNAME 

CONSTANT 
STATEMENT NUMBER 
VARIABLE 

HEX 

CHAR 

INTEG 

Any positional parameters that are not dependent upon delimiters 


RANGE 
Indicates to the parse service routine that two positional parameters are to 
be entered separated by a colon as follows: 


positional-parameter:positional-parameter 


The following positional parameter types may be used in the form of a 
range or a list of ranges: 


HEX (form X‘ ’ only) 

ADDRESS 

VALUE 

CONSTANT 

STATEMENT NUMBER 

VARIABLE 

INTEG 

Any positional parameter that is not dependent upon delimiters 


If the user at the terminal wants to enter a parameter that begins with a left 
parentheses, and you have specified in either the IKJPOSIT or IKJIDENT macro 
instruction that the parameter can be entered as a list or a range, the user must 
enclose the parameter in an extra set of parentheses to obtain the correct result. 


For instance, you have specified via the IKJPOSIT macro instruction that the 
dsname operand may be entered as a list, and the terminal user wishes to enter a 
dsname of the form: 


(membername) /password 


He must enter it as: 


((membername) /password) 
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Keyword Parameters 


Cc Keyword parameters can be entered anywhere in the command as long as they 
follow all positional parameters. They can consist of any combination of 
alphameric characters up to 31 characters long, the first of which must be an 
alphabetic character. 


You describe keyword parameters to the parse service routine with the 
IKJIKEYD, IKJNAME, and IKJSUBF macro instructions. 


| A keyword parameter can have a subfield of parameters associated with it. A 

| subfield contains positional and/or keyword parameters, and must be enclosed in 

| parentheses directly following its associated keyword parameter. (Separators can 

| appear between a keyword parameter and the opening parenthesis of its subfield. 

| In addition, separators can appear after the closing parenthesis of a subfield and 

| the following keyword parameter.) In the following example, posn! and kywd2 
are parameters in the subfield of keyword1: 


keyword1(posnl kywd2) 
The same syntax rules that apply to commands apply within keyword subfields. 
@ Keyword parameters must follow positional parameters. 


e Enclosing right parenthesis may be eliminated if the subfield ends at the end 
of a logical line. 


@ The subfield may not contain unbalanced right parentheses. 


If a keyword with a subfield in which there is a required parameter is entered 
without the subfield, the parse service routine prompts for the required parameter. 
The terminal user must not include the subfield parentheses when he enters the 
required parameter. 


If a subfield has a positional parameter that can be entered as a list, and if this is 
the only parameter in the subfield, the list must be enclosed by the same 
parentheses that enclose the subfield, such as: 


keyword(iteml item2 item3) 
where item1, item2, and item3 are members of a list. 
If a subfield has as its first parameter a positional parameter that may be entered 


as a list and there are additional parameters in the subfield, a separate set of 
parentheses is required to enclose the list, such as: 


keyword((iteml item2 item3) param) 


where item1, item2, and item3 are members of a list, and param is a parameter 
not included in the list. 
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Using the Parse Macro Instructions to Define Command Syntax 


A command processor using the parse service routine must build a parameter J 
control list (PCL) defining the syntax of acceptable command parameters. Each 

acceptable command parameter is described by a parameter control entry (PCE) 

within the PCL. The parse service routine compares the command parameters 

within the command buffer against the PCL to determine if valid command 

parameters have been entered. 


Parse returns the results of this comparison to the command processor in a 
parameter descriptor list (PDL). The PDL is composed of separate entries 
(PDEs) for each of the command parameters found in the command buffer. 


The command processor builds the PCL and the PCEs within it using the parse 
macro instructions. These macro instructions generate the PCL and establish 
symbolic references for the PDL returned by the parse service routine. 


The parse macros that generate input to parse can be issued in a program loaded 
above 16 Mb in virtual storage. The IKJRLSA macro can be issued in either 24- 
or 31-bit addressing mode. If the PCL resides above 16 Mb, once it has been 
passed to parse, the caller should not attempt to update it via a validity check 
exit. If the PCL resides below 16 Mb, the caller may update the PCL via a 
validity check exit after passing it to parse. 


There are eleven parse macro instructions: 


IKJPARM 
IKJPOSIT J 
IKJTERM 

IKJOPER 

IKJRSVWD 

IKJIDENT 

IKJKEYWD 

IKJNAME 

IKJSUBF 


IKJENDP 
IKJRLSA 


These macro instructions perform the following functions: 


1. When complete, all of the parse macros, except for IKJRLSA, return to the 
user’s CSECT. If a DSECT appears between the CSECT statement and the 
parse macro(s), an assembly error occurs. To prevent this error, place the 
DSECT after the macro(s). 


2. The IKJPARM macro instruction begins the PCL CSECT and the PDL 
DSECT, and provides symbolic addresses for both. 


3. The IKJPOSIT, IKJITERM, IKJOPER, IKJRSVWD, IKJIDENT, 
IKJKEYWD, IKJNAME, and IKJSUBF macro instructions describe the 
positional and keyword parameters valid for the command processor. These 
macro instructions expand into the PCEs required by the parse service routine , 
during its scan of the command buffer. The label fields of these macro J 
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instructions are used as labels within the DSECT that maps the PDL returned 
by the parse service routine. 


4. The IKJENDP macro instruction ends the PCL CSECT. 


5. The IKJRLSA macro instruction releases the virtual storage obtained by the 
parse service routine for the PDL. 


IKJPARM - Beginning the PCL and the PDL 


Code the IKJPARM macro instruction to begin the parameter control list and to 
provide a symbolic address for the beginning of the parameter descriptor list 
returned by the parse service routine. The PCL is constructed in the CSECT 
named by the label field of the macro instruction; the PDL will be mapped by the 
DSECT named in the DSECT operand of the macro instruction. 


Figure 15-13 shows the format of the IKJPARM macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


label | IKJPARM DSECT=]| dsect name 


IKIJPARMD 


Figure 15-13. The IKJPARM Macro Instruction 


label 
The name you provide is used as the name of the CSECT in which the PCL 
is constructed. 


DSECT = 
Provides a name for the DSECT created to map the parameter descriptor 
list. This may be any name; the default is IKJPARMD. 


The Parameter Control Entry Built By IKJPARM: The IKJPARM macro 
instruction generates the parameter control entry (PCE) shown in Figure 15-14. 
This PCE begins the parameter control list. 


Number 
of Bytes Contents or Meaning 


2 Length of the parameter control list. This field contains a hexadecimal 
number representing the number of bytes in this PCL. 

2 Length of the parameter descriptor list. This field contains a 
hexadecimal number representing the number of bytes in the parameter 
descriptor list returned by the parse service routine. 

Ps This field contains a hexadecimal number representing the offset within 
the PCL to the first. IKJKEYWD PCE or to an end-of-field indicator if 
there are no keywords. An end-of-field indicator may be an IKJSUBF 
or an IKJENDP PCE. 


Figure 15-14. The Parameter Control Entry Built by IKJPARM 


Chapter 15. Command Scan and Parse -- Determining the Validity of Commands 15-31 


IKJPOSIT - Describing a Delimiter-Dependent Positional Parameter 


Code the IKJPOSIT macro instruction to describe most of the J 
delimiter-dependent positional parameters. IKJIDENT is used to describe the 
others. 


The order in which you code the macros for positional parameters is the order in 
which the parse service routine expects to find the positional parameters in the 
command string. 


Figure 15-15 shows the format of the IKJPOSIT macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


label IKJPOSI SPACE 
DELIMITER 
STRING 
VALUE 
ADDRESS [,EXTENDED] [, LIST] [,RANGE] 
PSTRING 
USERID 
UID2PSWD 
DSNAME [, VOLSER] [,DDNAM] [,USID] 
DSTHING 
QSTRING 
JOBNAME 
[,SQSTRING] 
, UPPERCASE ,PROMPT='prompt data' 
,ASIS ,DEFAULT='default value' ) 
[,HELP=('help data','help data',...)] 
[, VALIDCK=symbolic-address] 


Figure 15-15. The IKJPOSIT Macro Instruction 


label 
This name is used as the symbolic address within the PDL DSECT of the 
parameter descriptor entry for the parameter described by this IKJPOSIT 
macro instruction. 


These are the positional parameter types recognized by the parse service 
routine. A syntactic definition of each is provided in “Delimiter-Dependent 
Parameters” earlier in this section. 


SPACE 
DELIMITER 
STRING 
VALUE 
ADDRESS 
PSTRING 
USERID 
UID2PSWD 
DSNAME 
DSTHING 


QSTRING 4 
JOBNAME 


15-32 TSO/E Guide to Writing a TMP or a CP 


SQSTRING 
The command operand is processed either as a string or as a quoted string. 
If the delimiter is an apostrophe, the command operand is processed as a 
quoted string. If the delimiter is any of the other acceptable delimiter 
characters, the command operand is processed as a string. The SQSTRING 
option can only be specified if STRING is specified for the parameter type. 
As an example, if SQSTRING is coded in the IKJPOSIT macro instruction, 
a terminal user entering a command could specify either: 


/string/string... 


Or 


'string' 'string' 


EXTENDED 
Specifies that the user may enter 31-bit addresses. This operand is valid 
only with ADDRESS. For more information, refer to the descriptions of 
absolute, relative, and indirect addresses and address expression under the 
description of the address parameter. 


LIST 
The command operands may be entered by the terminal user as a list: 


commandname (parameter,parameter, ...) 


This list option may be used with the following delimiter-dependent 
positional parameters: 


USERID, DSNAME, DSTHING, ADDRESS, VALUE, JOBNAME, 
and PSTRING (in subfield only). 


RANGE 
The command operands may be entered by the terminal user as a range: 


commandname parameter:parameter 


This range option may be used with the following delimiter-dependent 
positional parameters: 


ADDRESS 
VALUE 


VOLSER 
Specifies that a data set name is to be a volume serial name. This operand 
is valid only with DSNAME or DSTHING. If the first character is 
numeric, a maximum of six characters are allowed. 


DDNAM 
Specifies a data definition name. This option causes an INVALID 
DDNAME message if the name is invalid. 
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USID 
Specifies that the user identification is to prefix all data set names that J 
either are not entered in quotes or start with an asterisk. If you specify | 
USID and DSTHING and the first character of a data set name is an 
asterisk (*), the parse service routine does not prefix the user ID. 


Note: The following options (UPPERCASE, ASIS, PROMPT, 
DEFAULT, HELP, and VALIDCK) may be used with all 
delimiter-dependent positional parameters except SPACE and 
DELIMITER. 


UPPERCASE 
The parameter is to be translated to uppercase. 


ASIS 
The parameter is to be left as it was entered by the terminal user. 


PROMPT = ‘prompt data’ 
The parameter described by this IKJPOSIT macro instruction is required; 
the prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, the parse service routine adds a message-identifying 
number (message ID) and the word ENTER to the beginning of this 
message before writing it to the terminal. If prompting is necessary but the 
terminal is in no-prompt mode, the parse service routine adds a message ID 
and the word MISSING to the beginning of this message before writing it 


to the terminal. ) 


DEFAULT = ‘default value’ 
The parameter described by this IKJPOSIT macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered, the 
value specified as the default value is used. 


Note: If neither PROMPT nor DEFAULT is specified, the parameter is 
optional. The parse service routine takes no action if the parameter 
specified by this IKJPOSIT macro instruction is not present in the 
command buffer. 


HELP = (‘help data’,‘help data’...) 
You can provide up to 255 second level messages. (The assembler in use 
can limit the number of characters a macro operand with a sublist can 
contain.) Enclose each message in apostrophes and separate the messages 
by single commas. These messages are issued one at a time after each 
question mark is entered by the terminal user in response to a prompting 
message from the parse service routine. These messages are not sent to the 
user when the prompt is for a password on a dsname or userid parameter. 


Parse adds a message ID and the word ENTER (in prompt mode) or 


MISSING (in no-prompt mode) to the beginning of each message before 
writing it to the terminal. 
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VALIDCK = symbolic-address 
Supply the symbolic address of a validity checking subroutine if you want to 
perform additional validity checking on this parameter. Parse calls this 
routine after first determining that the parameter is syntactically correct. 


The Parameter Control Entry Built by IKJPOSIT: The IKJPOSIT macro 
instruction generates the variable length parameter control entry (PCE) shown in 
Figure 15-16. 


Number 
of Bytes Contents or Meaning 


Flags. These flags are set to indicate which options were specified in the 
IKJPOSIT macro instruction. 


This is an IKJPOSIT PCE. 
PROMPT 
DEFAULT 


This is an extended format PCE. If the VALIDCK parameter was 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 


HELP 
VALIDCK 


LIST 

ASIS 
RANGE 
SQSTRING 
USID 
VOLSER 
DDNAME 


Length of the parameter control entry. This field contains a 
hexadecimal number representing the number of bytes in this IKJPOSIT 
PCE. 


Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the related parameter descriptor entry built by the 
parse service routine. 


This field contains a hexadecimal number indicating the type of 
positional parameter described by this PCE. These numbers have the 
following meaning: 


HEX 


| 
2 
3 
4 
5 
6 
7 
8 
9 
A 
B 
C 
D 


DELIMITER 
STRING 
VALUE 
ADDRESS 
PSTRING 
USERID 
DSNAME 
DSTHING 
QSTRING 
SPACE 
JOBNAME 
UID2PSWD 
EXTENDED ADDRESS 
Eto FF Not used. 


Contains the length minus one of the default or 
prompting information supplied on the 
IKJPOSIT macro instruction. This field and the 
next are present only if DEFAULT or PROMPT 
was specified on the IKJPOSIT macro instruction. 


Variable This field contains the prompting or default 
information supplied on the IKJPOSIT macro instruction. 


Figure 15-16 (Part 1 of 2). The Parameter Control Entry Built by IKJPOSIT 
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Number 
of = Contents or Meaning 


This field contains a hexadecimal figure representing the length in bytes 

of all the PCE fields used for second level messages. The figure includes 
the length of this field. The fields are present only if HELP is specified 

on the IKJPOSIT macro instruction. 


This field contains a hexadecimal number representing the number of 
second level messages specified by HELP on this IKJPOSIT PCE. 


This field contains a hexadecimal number representing the length of this 
HELP segment. The length figure includes the length of this field, the 
message segment offset field, and the length of the information. These 
fields are repeated for each second level message specified by HELP on 
the IKJPOSIT macro instruction. 


This field contains the message segment offset. It is set to X‘0000’. 


2 
Variable 


This field contains one second level message supplied on the IKJPOSIT 
macro instruction specified by HELP. This field and the two preceding 
ones are repeated for each second level message supplied on the 
IKJPOSIT macro instruction. These fields do not appear if second level 
message data was not supplied. 


This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJPOSIT macro. If the “extended 
format PCE” bit is on in the IKJPOSIT PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 


Figure 15-16 (Part 2 of 2). The Parameter Control Entry Built by IKJPOSIT 


IKJTERM - Describing a Delimiter-Dependent Positional Parameter 


Code the IKJTERM macro instruction to describe a positional parameter that is 
one of the following: 


e Statement number 
e Constant 

e Variable 

& 


Constant or variable 


The order in which you code the macros for positional parameters is the order in 
which the parse service routine expects to find the parameters in the command 
string. 


Figure 15-17 shows the format of the IKJTERM macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


label | IKJTERM 'parameter-type'[,LIST] [,RANGE] 


, JPPERCASE STMT 

,ASIS , TYPE= (CNST 
VAR 
ANY 


[, SBSCRPT [=label-PCE]] |,PROMPT='prompt data' 
,DEFAULT='default value' | 


[,HELP=('help data','help data',...)] 
[, VALIDCK=symbolic~-address] [,RSVWD=label-PCE] 


Figure 15-17. The IKJTERM Macro Instruction 
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label 
This name 1s used to address the PCE built by the IKJTERM macro. The 
hexadecimal offset to the parameter descriptor entry described by this 
IKJTERM macro instruction 1s contained in the PCE. 


Note: The hexadecimal offset to the PDE will contain binary zero when the 
IKJTERM macro is describing a subscript of a data name. 


‘parameter-type’ 
This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and, if supplied, is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 


LIST 
The command operands may be entered by the terminal user as a list, in 
the form: 


commandname (parameter,parameter,...) 


The LIST option may be used with any of the TYPE= positional 
parameters. 


RANGE 
The command operands may be entered by the terminal user as a range, in 
the form: 


commandniame parameter:parameter 


The RANGE option may be used with any of the TYPE= positional 
parameters. 


Note: The LIST and RANGE options can not be used when the 
IKJTERM macro instruction is describing a subscript of a data-name. 


UPPERCASE 
The parameter is to be translated to uppercase. 


ASIS 
The parameter is to be left as it was entered by the terminal user. 


TYPE = 
Describes the type of the parameter as one of: 


STMT - statement number 
CNST - constant 

VAR - variable 

ANY - constant or variable 


Note: A syntactical definition of these parameters is contained under 
‘“Delimiter-Dependent Parameters.” 
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SBSCRIPT| = label-PCE] 
Specifies one of two conditions: ) 


1. If SBSCRIPT is entered with a label-PCE then the data-name described 
by the IKJTERM macro may be subscripted. Supply the name of the 
label of an IKJTERM macro instruction that describes the subscript. 
Only TYPE= VAR or TYPE=ANY parameters can be subscripted. 


2. If SBSCRPT is entered without a label-PCE then the IKJTERM macro 
is describing the subscript of a data-name. All TYPE= parameters may 
be used on a subscript except TYPE=STMT. The LIST and RANGE 
options can not be used on an IKJTERM macro that is describing a 
subscript. 


Note: Two IKJTERM macros are coded to describe a subscripted 
data-name. The first IKJTERM macro describes the data name and 
specifies the SBSCRIPT option with the label of the second IKJTERM 
macro. The second IKJTERM macro describes the subscript of the 
data-name and specifies SBSCRPT without a label-PCE. The second macro 
must immediately follow the first. 


PROMPT = ‘prompt data’ 
The parameter described by this IKJTERM macro instruction is required. 
The prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, the parse service routine adds a message-identifying 
number (message ID) and the word ENTER to the beginning of the message . 
before writing it to the terminal. J 


If prompting is necessary but the terminal is in no-prompt mode, the parse 
service routine adds a message ID and the word MISSING to the beginning 
of the message before writing it to the terminal. If a subscripted data-name 
requires prompting, the terminal user is prompted for the entire name 
including the subscript. 


DEFAULT = ‘default value’ 
The parameter described by this IKJTERM macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered, the 
value specified as the default value is used. 


Note: If neither PROMPT nor DEFAULT is specified, the parameter is 
optional. The parse service routine takes no action if the parameter is not 
present. 


HELP = (‘help data’,‘help data’,...) 
You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse service routine. 


Parse adds a message ID and the word ENTER (in prompt mode) or 
MISSING (in no-prompt mode) to the beginning of each message before 


writing it to the terminal. ) 
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VALIDCK = symbolic-address 
Supply the symbolic address of a validity checking subroutine if you want to 
perform additional checking on this parameter. Parse calls this routine after 
first determining that the parameter is syntactically correct. 


RSVWD = label-PCE 
This parameter is used when TYPE=CNST or TYPE=ANY is specified. 
This option indicates that this parameter can be a figurative constant. 
Supply the address of the PCE (label on a IKJRSVWD macro instruction) 
that begins the list of reserved words that can be entered as a figurative 
constant. 


This list of reserved words is defined by a series of IKJNAME macros that 
contain all possible names and immediately follow the IKJRSVWD macro. 


Note: The IKJRSVWD macro can be coded anywhere in the list of macros 
that build the PCL except following an IKJSUBF macro instruction. This 
permits other IKJTERM macro instructions to refer to the same list. 


The Parameter Control Entry Built by IKJTERM: The IKJTERM macro 
instruction generates the variable parameter control entry (PCE) shown in 
Figure 15-18. 


Number 
of Bytes Contents or Meaning 


Flags. These flags are set to indicate options on the IKJTERM macro 
instruction. 


This is an IKJTERM PCE. 
PROMPT 
DEFAULT 


This is an extended format PCE. If the VALIDCK parameter was 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 


HELP 
VALIDCK 


LIST 

ASIS 

RANGE 

This term may be SUBSCRIPTED. 

A reserved word PCE is chained from this term. 
Reserved 


The hexadecimal length of this PCE. 


Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the parameter descriptor entry built by the parse 
routine. 


This field indicates the type of positional parameter described by this 
PCE. 


STATEMENT NUMBER 
VARIABLE 

CONSTANT 

ANY (constant or variable) 

This term is a SUBSCRIPT term. 
Reserved 


Figure 15-18 (Part 1 of 2). The Parameter Control Entry Built by IKJTERM 
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Number 
of _ Contents or Meaning 


Contains the hexadecimal length of the parameter-type field. 
Contains the offset of the parameter-type field. It is set to X‘0012’. 
Variable Contains the parameter-type field. 


l Contains the length of the default or prompting information supplied on 
the macro instruction. 


Variable Contains the default or prompting information supplied on the macro 
instruction. 


If a subscript is specified on the macro, this field contains the offset into 
the parameter control list of the subscript PCE. 


If a reserved word PCE is specified on the macro, this field contains the 
offset into the parameter control list of the reserved word PCE. 


Contains the length (including this field) of all the PCE fields used for 
second level messages if HELP is specified on the macro. 


The number of second level messages specified on the macro instruction 
by the HELP parameter. 


Contains the length of this segment including this field, the message 
offset field and second level message. 
Note: This field and the following two are repeated for each second 
level message specified by HELP on the macro. 

2 This field contains the message segment offset. 


Variable This field contains one second level message specified by HELP on the 
macro instruction. This field and the two preceding fields are repeated 
for each second level message specified. 


3 or 4 This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJTERM macro. If the “extended 
format PCE” bit is on in the IKJTERM PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 


Figure 15-18 (Part 2 of 2). The Parameter Control Entry Built by IKJTERM J 


IKJOPER - Describing a Delimiter-Dependent Positional Parameter 


Code the IKJOPER macro instruction to provide a parameter control entry 
(PCE) that describes an expression. An expression consists of three parts; two 
operands and one operator in the form: 


(operandl operator operand2) 


typically entered as: 


(abc eq 123) 
The parts of an expression are described by PCEs that are chained to the 


IKJOPER PCE. The IKJTERM macro instruction is used to identify the 
operands, and the IKJRSVWD macro instruction is used to identify the operator. 
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Figure 15-19 shows the format of the IKJOPER macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


label | IKJOPER ‘parameter-type'|,PROMPT='prompt data' 
,DEFAULT='default value' 


[,HELP=('help data','help data',...)] 


[, VALIDCK=symbolic-address],OPERND1=labell 
,OPERND2=label2,RSVWD=label3 
[,CHAIN=label4] 


Figure 15-19. The IKJOPER Macro Instruction 


label 
This name is used to address the PCE built by the IKJOPER macro. The 
hexadecimal offset to the parameter descriptor entry described by this macro 
is contained in the PCE. 


‘parameter-type’ 
This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and if supplied is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 


Note: This field is used only with error messages for the complete 
expression. The IKJTERM and IKJRSVWD PCEs are used with an error 
message for missing operands or operator. If a validity check routine 
specifies an invalid expression, then the entire expression is prompted for. 


PROMPT = ‘prompt data’ 
The parameter described by this IKJOPER macro instruction is required. 
The prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, the parse service routine adds a message-identifying 
number (message ID) and the word ENTER to the beginning of the message 
before writing it to the terminal. If prompting is necessary but the terminal 
is in no-prompt mode, the parse service routine adds a message ID and the 
word MISSING to the beginning of the message before writing it to the 
terminal. 


DEFAULT = ‘default value’ 
The parameter described by this IKJOPER macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered the 
value specified as the default value is used. 


Note: If neither PROMPT nor DEFAULT is specified, the parameter is 


optional. The parse service routine takes no action if the parameter is not 
present. 
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HELP = (help data’,‘help data’,...) 
You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas, These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse service routine. 


Parse adds a message ID and the word ENTER (in prompt mode) or 
MISSING (in no-prompt mode) to the beginning of each message before 
writing it to the terminal. 


VALIDCK = symbolic-address 
Supply the symbolic address of a validity checking subroutine if you want to 
perform additional checking on this expression. The parse service routine 
calls this routine after first determining that the expression is syntactically 
correct. 


OPERND 1 =labell 
Supply the name of the label field of the IKJTERM macro instruction that 
is used to describe the first operand in the expression. This IKJTERM 
macro instruction should be coded immediately following the IKJOPER 
macro instruction that describes the expression. 


OPERND2 = label2 
Supply the name of the label field of the IKJTERM macro instruction that 
is used to describe the second operand in the expression. This IKJTERM 
macro instruction should be coded immediately following the IKJNAME 
macro instructions that describe the operator in the expression under the 
associated IKJRSVWD macro instruction. 


RSVWD = label3 
Supply the name of the label field of the IKJRSVWD macro instruction 
that begins the list of reserved words that are used to describe the possible 
operators to be entered for the expression. The IKJRSVWD and associated 
IKJNAME macro instructions should be coded immediately following the 
IKJTERM macro that describes the first operand, and immediately 
preceding the IKJTERM macro that describes the second operand. 


CHAIN = label4 
Indicates that this parameter described by the IKJOPER macro instruction 
may be entered as an expression or as a variable. Supply the name of the 
label field of an IKJTERM macro instruction that describes the variable 
term. The LIST and RANGE options are not permitted on this IKJTERM 
macro instruction. Code this IKJTERM macro instruction immediately 
following the IKJTERM macro that describes the second operand. 


Note: The parse service routine first determines if the parameter is entered 
as an expression. If the parameter is an expression, that is, enclosed in 
parentheses, then it is processed as an expression. If it is not an expression, 
then it is processed using the chained IKJTERM PCE to control the scan of 
the parameter. 
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J 


The Parameter Control Entry Built by IKJOPER: The IKJOPER macro 
instruction generates the variable parameter control entry (PCE) shown in 
Figure 15-20. 


Number 
of Bytes Contents or Meaning 


Variable 


2 
Variable 


3 or 4 


Byte 2 
0000 0000 


Flags. These flags are set to indicate options on the IKJOPER macro 
instruction. 


This is an IKJOPER PCE. 
PROMPT 
DEFAULT 


This is an extended format PCE. If the VALIDCK parameter is 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 


HELP 
VALIDCK 


Reserved 
The hexadecimal length of this PCE. 


Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the parameter descriptor entry built by the parse 
service routine. 


Contains the hexadecimal length of the parameter-type field. 
Contains the offset of the parameter-type field (X‘0012’). 
Contains the parameter-type field. 


If a reserved word PCE is specified on the macro, this field contains the 
offset into the parameter control list of the reserved word PCE. 


Contains the offset into the parameter control list of the OPERND1 
PCE. 


Contains the offset into the parameter control list of the OPERND2 
PCE. 


Contains the offset into the parameter control list of the chained term 
PCE if present. Zero if not present. 


Contains the length of the default or prompting information supplied on 
the macro instruction. 


Contains the default or prompting information supplied on the macro 
instruction. 


Contains the length (including this field) of all the PCE fields used for 
second level messages if HELP is specified on the macro. 


The number of second level messages specified on the macro instruction 
by the HELP= parameter. 


Contains the length of this segment including this field, the message 
offset field and second level message. 


Note: This field and the following two are repeated for each second 
level message specified by HELP on the macro. 


This field contains the message segment offset. 


This field contains one second level message specified by HELP on the 
macro instruction. This field and the two preceding fields are repeated 
for each second level message specified. 


This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJOPER macro. If the “extended 
format PCE” bit is on in the IKJOPER PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 


Figure 15-20. The Parameter Control Entry Built by IKJOPER 
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IKJRSVWD - Describing a Delimiter-Dependent Positional Parameter 


Code the IKJRSVWD macro instruction with at least the ‘parameter-type’ J 
operand when you use it: 


e With the RSVWD keyword of the IKJOPER macro instruction to define the 
beginning of a list of the possible reserved words that can be an operator in 
an expression. The possible reserved words that can be operators in an 
expression are identified by a list of IKJNAME macro instructions that 
immediately follow the IKJRSVWD macro instruction. 


e By itself to define a positional reserved word. 

Code the IKJRSVWD macro instruction without operands when you use it: 

e With the RSVWD keyword of the IKJTERM macro instruction to define the 
beginning of a list of possible reserved words that can be used as a figurative 
constant. The possible figurative constants are defined by a list of IKJNAME 


macros that immediately follow the IKJRSVWD macro instruction. 


In this case, simply code the IKJRSVWD macro instruction as: 


IKJRSVWD 


The order in which you code the macros for positional parameters is the order in 
which the parse service routine expects to find the parameters in the command } 
string. 


Figure 15-21 shows the format of the IKJRSVWD macro instruction. Each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


label | IKJRSVWD ‘parameter-type' |,PROMPT='prompt data' 
,DEFAULT='default value' 


[,HELP=('help data','help data',...)] 


Figure 15-21, The IKJRSVWD Macro Instruction 


label 
This name is used to address the PCE built by the IKJRSVWD macro. The 
hexadecimal offset to the parameter descriptor entry described by this macro 
1s contained in the PCE. 


Note: The following operands are not coded on the IKJRSVWD macro 


when you use it with the RSVWD keyword of the IKJTERM macro 
instruction. 
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‘parameter-type’ 
This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and if supplied is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 


PROMPT = ‘prompt data’ 
The parameter described by this IKJRSVWD macro instruction is required. 
The prompting data is the message to be issued if the parameter is not 
entered by the terminal user. If prompting is necessary and the terminal is 
in prompt mode, parse adds a message-identifying number (message ID) and 
the word ENTER to the beginning of the message before writing it to the 
terminal. If prompting is necessary but the terminal is in no-prompt mode, 
parse adds a message ID and the word MISSING to the beginning of the 
message before writing it to the terminal. 


DEFAULT = ‘default value’ 
The parameter described by this IKJRSVWD macro instruction is required, 
but the terminal user need not enter it. If the parameter is not entered, the 
value specified as the default value is used. 


Note: If neither PROMPT nor DEFAULT is specified, the parameter is 
optional. The parse service routine takes no action if the parameter is not 
present. 


HELP = (‘help data’,‘help data’,...) 
You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse routine. 


The parse service routine adds a message ID and the word ENTER (in 


prompt mode) or MISSING (in no-prompt mode) to the beginning of each 
message before writing it to the terminal. 
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The Parameter Control Entry Built by IKJRSVWD: The IKJRSVWD macro 
instruction generates the variable parameter control entry (PCE) shown in 


Figure 15-22. 


Number 
of Bytes Contents or Meaning 


000 0000 


Variable 
| 


Variable 


2 
Variable 


Flags. These flags are set to indicate options on the IKJRSVWD macro 
instruction. 


This is an IKJRSVWD PCE. 
PROMPT 

DEFAULT 

Reserved 

HELP 

Reserved 


This PCE is used with the IKJTERM macro as a figurative constant. 


This PCE is not used with the IKJTERM macro as a figurative 
constant. 


Reserved. 
The hexadecimal length of this PCE. 


Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the parameter descriptor entry built by the parse 
service routine. 


Note: The following fields are omitted if this PCE is used with the 
IKJTERM macro to describe a figurative constant. 


Contains the hexadecimal length of the parameter-type field. 
Contains the offset of the parameter-type field (X‘0012’). 
Contains the parameter-type field. 


Contains the length of the default or prompting information supplied on 
the macro instruction. 


Contains the default or prompting information supplied on the macro 
instruction. 


Contains the length (including this field) of all the PCE fields used for 
second level messages if HELP is specified on the macro. 


The number of second level messages specified on the macro instruction 
by the HELP= parameter. 


Contains the length of this segment including this field, the message 
offset field and second level message. 

Note: This field and the following two are repeated for each second 
level message specified by HELP on the macro. 

This field contains the message segment offset. 


This field contains one second level message specified by HELP on the 
macro instruction. This field and the two preceding fields are repeated 
for each second level message specified. 


Figure 15-22. The Parameter Control Entry Built by IKJIRSVWD 


IKJIDENT - Describing a Non-Delimiter-Dependent Positional Parameter 


Execute the IKJIDENT macro instruction to describe a positional parameter that 
does not depend upon a particular delimiter for its syntactical definition -- those 
parameters discussed under “Positional Parameters Not Dependent on 


Delimiters.” 


These positional parameters must be in the form of a character string, with 
restrictions on the beginning character, additional characters, and length, decimal 
integers, or hexadecimal characters. 
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The order in which you code the macro instructions for positional parameters is 
the order in which the parse service routine expects to find the positional 
parameters in the command string. 


Figure 15-23 shows the format of the IKJIDENT macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


label | IKJIDENT 'parameter-type' [,LIST][,RANGE][,PTBYPS] 


ARs een nee) 
,ASIS 


ALPHANUM ; = JALPHANUM 
ANY ANY 

NONATABC NONATABC 
NONATNUM NONATNUM 


,PROMPT='prompt data' 
,DEFAULT='default value' 


, VALIDCK=symbolic~address] 
,HELP=('help data', ‘help data' 


ALPHA ALPHA 
NUMERIC NUMERIC 
[ 
[ 


Figure 15-23. The IKJIDENT Macro Instruction 


label 
This name is used within the PDL DSECT as the symbolic address of the 
parameter descriptor entry for this positional parameter. 


‘parameter-type’ 
This field is required so that the parameter can be identified when an error 
message is necessary. This field differs from the PROMPT field in that the 
PROMPT field is not required and if supplied is used only for a required 
parameter that is not entered by the terminal user. Blanks within the 
apostrophes are allowed. 


LIST | 


This positional parameter may be entered by the terminal user as a list, that 
is, in the form: 


commandname (parameter,parameter,...) 


RANGE 


This positional parameter may be entered by the terminal user as a range, 
that is, in the form: 


commandname parameter:parameter 


If you specify RANGE and OTHER =ANY, parse treats any colons it finds 
as delimiters. For example, the first colon after RANGE marks the end of 
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the first part of the range and the start of the next part of the range. To 
include the colon in your data, you must use the CHAR operand and 
enclose the colon by quotation marks. ) 


PTBYPS 
All prompting for the parameter is to be done in print inhibit mode. This 
option may be specified only when the PROMPT option is specified. 


ASTERISK 
An asterisk may be substituted for this positional parameter. 


Note: ASTERISK and INTEGER are mutually exclusive. 


UPPERCASE 
The parameter is to be translated to uppercase. 


ASIS 
The parameter is to be left as it was entered. 


MAXLNTH = number 
The maximum number of characters the string may contain. If you do not 
code the MAXLNTH operand, the parse service routine accepts a character 
string of any length. 


FIRST = 
Specify the character type restriction on the first character of the string. 


OTHER = ) 
Specify the character type restriction on the characters of the string other 
than the first character. 


Note: The restrictions on the characters of the string are specified by 
coding one of the following character types after the FIRST = and the 
OTHER= operands. This is true unless HEX, INTEG, or CHAR is 

specified. FIRST= and OTHER = serve no purpose in these cases. 


ALPHA 
An alphabetic or national character. ALPHA is the default value for both 
the FIRST and the OTHER operands. 


NUMERIC 
A digit, 0-9. 


ALPHANUM 
An alphabetic, numeric, or national character. 


ANY 
Any character other than a blank, comma, tab, or semicolon. Parentheses 
must be balanced. 


NONATABC 
An alphabetic character only. National characters and numerics are 


excluded. y 
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NONATNUM 
An alphabetic or numeric character. National characters are excluded. 


PROMPT = ‘prompt data’ 
The parameter is required; the prompting data is the message to be issued if 
the parameter is not entered by the terminal user. If prompting is necessary 
and the terminal is in prompt mode, the parse service routine adds a 
message-identifying number (message ID) and the word ENTER to the 
beginning of this message before writing it to the terminal. If prompting is 
necessary but the terminal is in no-prompt mode, the parse service routine 
adds a message ID and the word MISSING to the beginning of this message 
before writing it to the terminal. 


DEFAULT = ‘default value’ 
The parameter is required, but a default value may be used. If the 
parameter is not entered by the terminal user, the value specified as the 
default value is used. 


Note: The parameter is optional if neither PROMPT nor DEFAULT is 
specified. The parse service routine takes no action if the parameter 
specified by this IKJIDENT macro instruction is not present in the 
command buffer. 


CHAR 
Specifies that the parse service routine is to accept a string of characters as 
input. This input string may be either quoted or unquoted. 


INTEG 
Specifies that the parse service routine is to accept a numeric quantity as 
input. This quantity may be decimal, hexadecimal, or binary. The number 
is stored internally as a fullword binary value, regardless of how INTEG 
was specified. 


Note: A maximum length is automatically implied if the INTEG option is 
specified. For binary input, the maximum number of characters is 32. For 
hexadecimal input, the maximum length is 8. For decimal input, the 
maximum length is 10. 


HEX 
Specifies that the parse service routine is to accept a hexadecimal value as 
input. This string quantity may be hexadecimal or a quoted or non-quoted 
string. 


Note: All input entered in the form X‘n...’ must be valid hexadecimal digits 
(0-9, A-F). All input entered in the form B¥‘n...’ must be valid binary digits 
(0,1). All input entered as unquoted decimals must be valid decimal digits 
(0-9). 


VALIDCK = symbolic-address 
Supply the symbolic address of a validity checking subroutine if you want to 
perform additional validity checking on this parameter. The parse service 
routine calls the addressed routine after first determining that the parameter 
is syntactically correct. 
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HELP = (‘help data’,‘help data’...) 
You can provide up to 255 second level messages. Enclose each message in 
apostrophes and separate the messages by single commas. These messages 
are issued one at a time after each question mark entered by the terminal 
user in response to a prompting message from the parse service routine. 
These messages are not sent to the user when the prompt is for a password 
on a dsname or userid parameter. 


The parse service routine adds a message ID and the word ENTER (in 
prompt mode) or MISSING (in no-prompt mode) to the beginning of each 
message before writing it to the terminal. 


The Parameter Control Entry Built by IKJIDENT: The IKJIDENT macro 


instruction generates the variable length parameter control entry (PCE) shown in 
Figure 15-24. 
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Number 
of Bytes Field Contents or Meaning 


Flags. These flags are set to indicate which options were specified in the 
IKJIDENT macro instruction. 


This is an IKJIDENT PCE. 
PROMPT 
DEFAULT 


This is an extended format PCE. If the VALIDCK parameter is 
specified, the length of the field containing the address of the validity 
checking routine is four bytes. 


HELP 
VALIDCK 


LIST 
ASIS 
RANGE 
Reserved 


Length of the parameter control entry. This field contains a 
hexadecimal number representing the number of bytes in this 
IKJIDENT PCE. 


Contains a hexadecimal offset from the beginning of the parameter 
descriptor list to the related parameter descriptor entry built by the 
parse service routine. 


A flag field indicating the options coded on the IKJIDENT macro 
instruction. 


ASTERISK 
MAXLNTH 
PTBYPS 
Integer 
Character 
Hexadecimal 
Reserved 


This field contains a hexadecimal number indicating the character type 
restriction on the first character of the character string described by the 
IKJIDENT macro instruction. 


HEX Acceptable characters: 


Any (except blank, comma, tab, semicolon) 
Alphabetic or national 
Numeric 
Alphabetic, national, or numeric 
Alphabetic 
Alphabetic or numeric 

6to FF Not used 


This field contains a hexadecimal number indicating the character type 
restriction on the other characters of the character string described by 
the IKJIDENT macro instruction. 


HEX Acceptable characters: 


Any (except blank, comma, tab, semicolon) 
Alphabetic or national 

Numeric 

Alphabetic, national, or numeric 
Alphabetic 

Alphabetic or numeric 

Not used 


Figure 15-24 (Part 1 of 2). The Parameter Control Entry Built by IKJIDENT 
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Number 
of Bytes Contents or Meaning 


This field contains a hexadecimal number representing the length of the 
parameter type segment. This figure includes the length of this field, the 
length of the message segment offset field. and the length of the 
parameter type field supplied on the IKJIDENT macro instruction. 


2 This field contains the message segment offset. I1 is set to X‘0012’. 


Variable This field contains the field supplied as the parameter type operand of 
the IKJIDENT macro instruction. 


This field contains a hexadecimal number representing the maximum 
number of characters the string may contain. This field is present only 
if the MAXLNTH operand was coded on the IKJIDENT macro 
instruction. 


This field contains the length minus one of the defaults or prompting 
information supplied on the IKJIDENT macro instruction. This field 
and the next are present only if DEFAULT or PROMPT were specified 
on the IKJIDENT macro instruction. 


Variable This field contains the prompting or default information supplied on the 
IKJIDENT macro instruction. 


This field contains a hexadecimal figure representing the length in bytes 

of all the PCE fields used for second level messages. The figure includes 
the length of this field. The fields are present only if HELP is specified 

on the IKJIDENT macro instruction. 


This field contains a hexadecimal number representing the number of 
second level messages specified by HELP on this IKJIDENT PCE. 


This field contains a hexadecimal number representing the length of this 
HELP segment. The figure includes the length of this field, the message 
segment offset field, and the length of the information. These fields are 
repeated for each second level message specified by HELP on the 
IKJIDENT macro instruction. 


2 This field contains the message segment offset. It is set to X‘0000". 


Variable This field contains one second level message supplied on the IKJIDENT 
macro instruction specified by HELP. This field and the two preceding 
ones are repeated for each second level message supplied on the 
IKJIDENT macro instruction; these fields do not appear if no second 
level message data was supplied. 


This field contains the address of a validity checking routine if 
VALIDCK was specified on the IKJIDENT macro. If the “extended 
format PCE” bit is on in the IKJIDENT PCE, the address is four bytes 
long; if the bit is off, the address is three bytes long. This field is not 
present if VALIDCK was not specified. 


Figure 15-24 (Part 2 of 2). The Parameter Control Entry Built by IKJIDENT 


IKJKEYWD - Describing a Keyword Parameter 


Execute the IKJKEYWD macro instruction to describe a keyword parameter. 
Execute a series of IKJNAME macro instructions to indicate the possible names 
for the keyword parameter. Keyword parameters may appear in any order in the 
command but must follow all positional parameters. A user is never required to 
enter a keyword parameter; if he does not, the default value you supply, if you 
choose to supply one, is used. Keywords may consist of any combination of 
alphameric characters up to 31 characters in length, the first of which must be an 
alphabetic character. 


15-52 TSO/E Guide to Writing a TMP or a CP 


Figure 15-25 shows the format of the IKJKEYWD macro instruction. Each of 
the operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


[DEFAULT='default-value' | 


Figure 15-25. The IKJKEYWD Macro Instruction 


label 
This name is used within the PDL DSECT as the symbolic address of the 
parameter descriptor entry for this parameter. 


DEFAULT = ‘default-value’ 
The default value you specify is the value that is used if this keyword is not 
present in the command buffer. Specify the valid keyword names with 
IKJNAME macro instructions following this IKJKEYWD macro 
instruction. 


The Parameter Control Entry Built by IKJKEYWD: The IKJKEYWD macro 
instruction generates the variable length parameter control entry (PCE) shown in 
Figure 15-26. 


Number 
of Bytes Field Contents or Meaning 


Flags. These flags are set to indicate which options were coded in the 
IKJKEYWD macro instruction. 


This is an IKJIKEYWD PCE. 
Reserved. 
ee DEFAULT 
....  .000 Reserved. 
Byte 2 
0000 0000 Reserved. 
Length of the parameter control entry. This field contains a 


hexadecimal number representing the number of bytes in this 
IKJKEYWD PCE. 


This field contains a hexadecimal offset from the beginning of the 
parameter descriptor list to the related parameter descriptor entry built 
by the parse service routine. 


This field contains the length minus one of the default information 
supplied on the IKJKEYWD macro instruction. This field and the next 
are present only if DEFAULT was specified on the IKJKEYWD macro 
instruction. 


Variable This field contains the default value supplied on the IKJKEYWD macro 
instruction. 


Figure 15-26. The Parameter Control Entry Built by IKJKEYWD 
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IKJNAME - Listing the Keyword or Reserved Word Parameter Names 


The IKJNAME macro instruction may be coded with the following two macro 
instructions: 


|. With the IKJKEYWD macro instruction to define keyword parameter names. 


2. With the IKJRSVWD macro instruction to define reserved word parameter 
names. 


A description and format of the IKJNAME macro instruction for both methods 
of coding follows: 


|. Code a series of IKJNAME macro instructions to indicate the possible names 
for a keyword parameter. One IKJNAME macro instruction is needed for 
each possible keyword name. Code the IKJNAME macro instructions 
immediately following the IKJKEYWD macro instruction to which they 
pertain. 


Figure 15-27 shows the format of the IKJNAME macro instruction. Each of 
the operands is explained following the figure. Appendix A describes the 
notation used to define macro instructions. 


IKJNAME 'keyword-name' [,SUBFLD=subfield-name] 
[, INSERT='keyword-string' ] 


[ ,ALIAS=('name','name',...)] 


Figure 15-27. The IKJNAME Macro Instruction (when used with the IKJKEYWD 
Macro Instruction) 


keyword-name 
One of the valid keyword parameters for the IKJKEYWD macro 
instruction that precedes this IKJNAME macro instruction. 


SUBFLD = subfield-name 
This option indicates that this keyword name has other parameters 
associated with it. Use the subfield-name as the label field of the 
IKJSUBF macro instruction that begins the description of the possible 
parameters in the subfield. 


INSERT = ‘keyword-string’ 
The use of some keyword parameters may imply that other keyword 
parameters are required. The parse service routine inserts the keyword 
string specified into the command string just as if it had been entered as 
part of the original command string. The command buffer is not 
altered. 


ALIAS = (‘name’,‘name’,...) 
Specifies up to 32 alias names for a keyword. Each name represents a 
valid abbreviation or alternate name and must be enclosed in quotes. 
All abbreviations or names must be enclosed in a single set of 
parentheses. 
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2. Code a series of IKJNAME macro instructions to indicate the possible names 
for reserved words. One IKJNAME macro instruction is needed for each 
possible reserved word name. Code the IKJNAME macro instructions 
immediately following the IKJRSVWD macro instruction to which they 


apply. 


Figure 15-28 shows the format of the IKJNAME macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


= 


Figure 15-28. The IKJNAME Macro Instruction (when used with the IKJRSVWD 
Macro Instruction) 


reserved-word name 
One of the valid reserved word parameters for the IKJRSVWD macro 
instruction that precedes the IKJNAME macro instructions. 


Note: The IKJNAME macro instruction has two uses when coded with the 
IKJRSVWD macro instruction. The reserved-words identified on the 
IKJNAME macros may be figurative constants when the IKJRSVWD 
macro is chained from an IKJTERM macro, or operators in an expression 
when the IKJRSVWD macro is chained from the IKJOPER macro. 


The Parameter Control Entry Built by IKJNAME: The IKJNAME macro 
instruction generates the variable length parameter control entry (PCE) shown in 


Figure 15-29. 


Note: Only the first four fields are valid when the IKJNAME macro instruction 
is coded with the IKJRSVWD macro instruction. 
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umber 
ges [st coor mig 


Flags. These flags are set to indicate which options were coded in the 
IKJNAME macro instruction. 


This is an IKJNAME PCE. 
Reserved. 
SUBFLD 
Reserved. 


Reserved. 
INSERT 
ALIAS 
Reserved. 


Length of the parameter control entry. This field contains a 
hexadecimal number representing the number of bytes in this 
IKJNAME PCE. 


This field contains the length minus one of the keyword or reserved 
word names specified on the IKJNAME macro instruction. 


Variable This field contains the keyword or reserved word name specified on the 
IKJNAME macro instruction. 


This field contains a hexadecimal offset, plus one, from the beginning of 
the parameter control list to the beginning of a subfield PCE. This field 
is present only if the SUBFLD operand was specified in the IKINAME 
macro instruction. 


This field contains the length minus one of the keyword string included 
as the INSERT operand in the IKJNAME macro instruction. This field 
and the next are not present if INSERT was not specified. 


Variable This field contains the keyword string specified as the INSERT operand 
of the IKJNAME macro instruction. 


The total number of aliases. 


1 The length minus one of first alias. 
Variable The first alias. 
l The length minus one of second alias. 


Variable The second alias. 


Figure 15-29. The Parameter Control Entry Built by IKJINAME 


IKJSUBF - Describing a Keyword Subfield 


Keyword parameters may have subfields associated with them. A subfield 
consists of a parenthesized list of parameters directly following the keyword. 


Execute the IKJSUBF macro instruction to indicate the beginning of a subfield 
description. The IKJSUBF macro instruction ends the main part of the 
parameter control list or the previous subfield description, and begins a new 
subfield description. 


Note that the IKJSUBF macro instruction is used only to begin the subfield 
description; the subfield is described using the IKJPOSIT, IKJIDENT, and 
IKJKEYWD macro instructions, depending upon the type of parameters within 
the subfield. 


You must use the name you have coded as the SUBFLD operand of the 
IKJNAME macro instruction for the label of this macro instruction. 
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Figure 15-30 shows the format of the IKJSUBF macro instruction. Appendix A 
describes the notation used to define macro instructions. 


Figure 15-30. The IKJSUBF Macro Instruction 


label 
The name you supply as the label of this macro instruction must be the 
same name you have coded as the SUBFLD operand of the IKJNAME 
macro instruction describing the keyword name that takes this subfield. 


The Parameter Control Entry Built by IKJSUBF: The IKJSUBF macro 
instruction generates the parameter control entry (PCE) shown in Figure 15-31. 


Number 
of ae Field Contents or Meaning 


Flags. These flags indicate which type of PCE this is. 


This PCE indicates an end-of-field. These end-of-field indicators are 
present in IKJSUBF and IKJENDP PCEs; they indicate the end of a 
previous subfield or of the PCL itself. 


Reserved. 


This field contains a hexadecimal number representing the offset within 
the PCL to the first IKJKEYWD PCE or to the next end-of-field 
indicator if there are no keywords in this subfield. 


Figure 15-31. The Parameter Control Entry Built by IKJSUBF 


IKJENDP - Ending the Parameter Control List 


Execute the IKJENDP macro instruction to inform the parse service routine that 
it has reached the end of the parameter control list built for this command. 


Figure 15-32 shows the format of the IKJENDP macro instruction. Appendix A 
describes the notation used to define macro instructions. 


IKJENDP 


Figure 15-32. The IKJENDP Macro Instruction 


The Parameter Control Entry Built by IKJENDP: The IKJENDP macro 
instruction generates the parameter control entry (PCE) shown in Figure 15-33. 
It is merely an end-of-field indicator. 


umber 


Flags. These flags are set to indicate end-of-field. 


End-of-field indicator. Indicates the end of the PCL. 
Reserved. 


Figure 15-33. The Parameter Control Entry Built by IKJENDP 


Chapter 15. Command Scan and Parse -- Determining the Validity of Commands 15-57 


IKJRLSA - Releasing Virtual Storage Allocated by Parse 


Execute the IKJRLSA macro instruction to release virtual storage allocated by J 
the parse service routine and not previously released by the parse service routine. 

This storage consists of the parameter descriptor list (PDL) returned by the parse 

service routine and any virtual storage obtained for new data received by parse as 

a result of a prompt. 


If the return code from the parse service routine is non-zero, all virtual storage 
allocated by parse has been freed by the parse service routine. In that case, this 
macro instruction need not be issued, but will not cause an error if it is issued. 


Figure 15-34 shows the format of the IKJRLSA macro instruction. Each of the 
operands is explained following the figure. Appendix A describes the notation 
used to define macro instructions. 


label IKJRLSA Address of the answer place 


(1-12) 


Figure 15-34. The IKJRLSA Macro Instruction 


address of the answer place 
The address of the word in which the parse service routine placed a pointer 
to the PDL when control was returned to the command processor. This 
address may be loaded into one of the general registers 1 through 12, right 
adjusted with the unused high order bits set to zero. See “Passing Control 
to the Parse Service Routine” for a description of the parse parameter list. J 


Passing Control to the Parse Service Routine 


You pass control to the parse service routine by issuing a CALLTSSR macro 
instruction specifying IKJPARS as the entry point. Before you invoke the parse 
service routine however, you must build a parse parameter list (PPL), and place 
its address into register 1. This PPL must remain intact until the parse service 
routine returns control to the calling routine. Figure 15-35 shows this flow of 
control between a command processor and the parse service routine. 
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CALLTSSR 


Command Processor EP = IKIPARS Parse Service Routine 


User Work Area 


Figure 15-35. Control Flow between Command Processor and the Parse Service Routine 


The Parse Parameter List 


The parse parameter list (PPL) is a seven-word parameter list containing addresses 
required by the parse service routine. 
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The PPL its defined by the IKJPPL DSECT. Figure 15-36 shows the format of 
the parse parameter list. 


Number 
of _ Field Contents or Meaning 


PPLUPT The address of the user profile table. 
PPLECT 
PPLECB 


The address of the environment control table. 


The address of the command processor’s event control] block. The ECB 
is one word of storage, declared and initialized to zero by the command 
processor. 


PPLPCL The address of the parameter control list created by the command 
processor using the parse macro instructions. Use the label on the 


IKJPARM macro instruction as the symbolic address of the PCL. 


The address of a fullword of virtual storage, supplied by the calling 
routine, in which the parse service routine places a pointer to the 
parameter descriptor list (PDL). If the parse of the command buffer is 
unsuccessful, parse sets the pointer to the PDL to X*FF000000". 


The address of the command buffer. 


PPLANS 


PPLCBUF 
PPLUWA 


The user supplied work area. This field can contain anything that the 
calling routine wishes passed to a validity checking routine. 


Figure 15-36. The Parse Parameter List 


Formats of the PDEs Returned by the Parse Service Routine 


The PDL Header 


The parse service routine returns the results of the scan of the command buffer to 
the command processor in a parameter descriptor list (PDL). The PDL, built by 
parse, consists of the parameter descriptor entries (PDE), which contain pointers 

to the parameters, indicators of the options specified, and pointers to the subfield 
parameters entered with the command operands. 


Use the IKJPARMD DSECT to map the PDL and each of the PDEs. Base the 
IKJPARMD DSECT on the PDL address returned by the Parse service routine. 
The PPLANS field of the parse parameter list points to a fullword of storage that 
contains the address of the PDL. Then use the labels you used on the parse 
macro instructions to access the corresponding PDEs. 


The format of the PDE depends upon the type of parameter parsed. For a 
discussion of parameter types, see the topic “Command Parameter Syntax.” The 
following description of the possible PDEs within a PDL shows each of the PDE 
formats and the type of parameters they describe. 


The PDL begins with a two-word header. The DSECT= operand of the 
IKJPARM macro instruction provides a name for the DSECT created to map the 
PDL. Use this name as the symbolic address of the beginning of the PDL header. 


A pointer to the next block of virtual storage 


Subpool number 
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Pointer to the next block of virtual storage: 
The parse service routine gets virtual storage for the PDL and for any data 
received as the result of a prompt. Each block of virtual storage obtained 
begins with another PDL header. The blocks of virtual storage are forward 
chained by this field. A forward-chain pointer of X‘FFO00000’ in this field 
indicates that this is the last storage element obtained. 


Subpool number: 
This field will always indicate subpool 1. All virtual storage allocated by 
the parse service routine for the PDL and for data received from a prompt 
is allocated from subpool 1. 


Length: 
This field contains a hexadecimal number indicating the length of this block 
of real storage (this PDL); the length includes the header. 


PDEs Created for Positional Parameters 


The labels you use to name the macro instructions provide access to the 
corresponding PDEs. The positional parameters described by the IKJPOSIT, 
IKJTERM, IKJOPER, IKJRSVWD and the IKJIDENT macro instructions have 
the following PDE formats. 


SPACE, DELIMITER: The parse service routine does not build a PDE for 
either a SPACE or a DELIMITER parameter. 


STRING, PSTRING, and QSTRING: The parse service routine uses the 
IKJPOSIT macro to build a two-word PDE to describe a STRING, PSTRING, 
or a QSTRING parameter; the PDE has the following format: 


A pointer to the character string 


Reserved 


Pointer to the character string: 
Contains a pointer to the beginning of the character string, or a zero if the 
parameter was omitted. 


Length: 
Contains the length of the string. Any punctuation around the character 
string is not included in this length figure. The length is zero if the string is 
omitted or if the string is null. 


Flags: 


One. 2% The parameter is not present. 
Vssee xine The parameter is present. 
XXX XXxx Reserved bits. 


Note: If the string is null, the pointer is set, the length is zero, and the flag 
bit is 1. 
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VALUE: The parse service routine uses the IKJPOSIT macro to build a 
two-word PDE to describe a VALUE parameter; the PDE has the following 
format: 


+0 


A pointer to the character string 


+4 +6 +7 
Length Flags Type-char. 


Pointer to the character string: 
Contains a pointer to the beginning of the character string; that is, the first 
character after the quote. Contains a zero if the VALUE parameter is not 


present. 
Length: 

Contains the length of the character string excluding the quotes. 
Flags: 

eee The parameter is not present. 

Dice: eke The parameter is present. 


.XXX XXXX Reserved bits. 


Type-character: 
Contains the letter that precedes the quoted string. 


DSNAME, DSTHING: The parse service routine uses the IKJPOSIT macro 


instruction to build a six-word PDE to describe a DSNAME or a DSTHING 
parameter. The PDE has the following format: 


Pointer to the dsname: 
Contains a pointer to the first character of the data set name. Contains 
zero if the data set name was omitted. Contains a pointer to the USID if it 
is prefixed. 


Lengthl: 
Contains the length of the data set name. If the data set name is contained 
in quotes, this length figure does not include the quotes. When the USID is 
prefixed, this field will contain the total length of the data set name and the 
USID. 
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Flags1: 


0... The data set name is not present. 

Liss The data set name is present. 

0. The data set name is not contained within quotes. 
Als 


seh The data set name is contained within quotes. 
XX XXXX Reserved bits. 


Pointer to the member name: 


Contains a pointer to the beginning of the member name. Contains zero if 
the member name was omitted. 


Length?2: 
Contains the length of the member name. This length figure does not 
include the parentheses around the member name. 


Flags2: 
eee The member name is not present. 
| eee The member name is present. 


XXX XXXX Reserved bits. 


Pointer to the password: 


Contains a pointer to the beginning of the password. Contains zero if the 
password was omitted. 


Length3: 

Contains the length of the password. 
Flags3: 

Ord S58 The password is not present. 

Lice. ats The password is present. 


XXX XXXX Reserved bits. 


JOBNAME: The parse service routine uses the IKJPOSIT macro to build a four 


word PDE to describe a JOBNAME parameter. The PDE has the following 
format: 


Pointer to the jobname: 


Contains a pointer to the beginning of the jobname. Contains zero if the 
jobname was omitted. 


Length1: 


Contains the length of the jobname. The jobname may not be entered in 
quotes. 
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Flags: 


Vise. . oie The jobname is not present. 
eer The jobname is present. 


Pointer to the jobid: 
Contains a pointer to the beginning of the jobid. Contains zero if the jobid 
was omitted. 


Length2: 
Contains the length of the jobid. This length figure does not include the 
parentheses around the jobid. 


Flags2: 
Oe: “text The jobid is not present. 
ee The jobid is present. 


XXX Xxxx Reserved bits. 


ADDRESS: The parse service routine uses the IKJPOSIT macro to build a nine 
word PDE to describe an ADDRESS parameter. The PDE has the following 
format: 


A pointer to the load name 


+4 
Lengthl Flags 1 Reserved 


+8 
A pointer to the entry name 


+12 +15 


Length2 Flags2 Reserved 


+ 16 


A pointer to the address string 
+22 


+ 23 
Length3 Flags3 Reserved 
+24 +25 + 26 
Flags4 Sign Indirect count 
+28 
A pointer to the first expression value PDE 
+32 
Reserved for use by user validity check routine 


Pointer to the load name: 
Contains a pointer to the beginning of the load module name. Contains 
zero if no load module name was specified. 


+20 


Length1: 

Contains the length of the load module name, excluding the period. 
Flags]: 

O.2.. «sae The load module name is not present. 

\ The load module name is present. 


.XXX XXXX Reserved bits. 
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Pointer to the entry name: 
Contains a pointer to the name of the CSECT; zero if the CSECT name is 
not specified. 


Length2: 

Contains the length of the entry name, excluding the period. 
Flags2: 

Oise: The entry name is not present. 


EOP The entry name is present. 
XXX XXxx Reserved bits. 


Pointer to the address string: 
Contains a pointer to the address string portion of a qualified address. 
Contains a zero if the address string was not specified. 


Length3: 
Contains the length of the address string portion of a qualified address. 
This length count excludes the following characters for the following address 
types: 


1. Relative address - excludes the plus sign. 
2. Register address - excludes letters. 
3. Absolute address - excludes period. 


Flags3: 
The bits set in this one-byte flag field indicate whether the address string is 
present and what type of indirect address is represented. 


Gio. cae The address string is not present. 

Ieee. . sats The address string is present. 

lees -wk A 31-bit indirect address is represented. 
Ales: att A 24-bit indirect address is represented. 


XX Xxxx Reserved bits. 
Notes: 


1. Bit 1 of Flags3 has no meaning if the indirect count is zero. This bit can 
be on only when the EXTENDED keyword of IKJPOSIT has been 


specified. 
2. Bit 0 and I have the same meaning for MVS 370, but 2 through 16 are 
reserved. 
Offset 23: 


This byte is reserved for use by the user’s validity check routine. 
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Flags4: 
The bits set in this one-byte flag field indicate the type of address found by 
the parse service routine. 


Bit Setting Hex Meaning 


0000 0000 00 Absolute address. 

1000 0000 80 Symbolic address. 

0100 0000 40 Relative address. 

0010 0000 20 General register. 

0001 0000 10 Double precision floating-point register. 

0000 1000 08 Single precision floating-point register. 

0000 0100 04 Non-qualified entry name (optionally preceded by a load name). 


Sign: 
Contains the arithmetic sign character used before the expression value 
defined by the first expression value PDE. If the sign field is zero and the 
pointer to the first expression value PDE is non-zero, then the first 
expression value PDE was created due to a switch in indirection symbols 
(2% or %?). If there are no address expression PDEs, then this field is zero. 


Indirect count: 
Contains a number representing the number of levels of indirect addressing. 


Pointer to the first expression value PDE: 
This is a pointer to the first expression value PDE. Contains X*FF000000’ 
if there are no expression value PDEs. 


User word for validity checking routine: | 
A word provided for use by the user-written validity checking routine. } 


Expression Value: If the parse service routine finds an ADDRESS parameter to 
be in the form of an address expression, parse builds an expression value PDE for 
each expression value in the address expression. 


If the EXTENDED keyword is specified on the IKJPOSIT macro, and parse 
encounters an alternating sequence of indirection symbols, (%? or ?%), parse 
completes the current PDE and generates a new expression value PDE. 


These expression value PDEs are chained together, beginning at the eighth word 
of the address PDE built by the parse service routine to describe the address 
parameter. The last expression value PDE is indicated by X‘FF000000’ in its 
fourth word, the forward chaining field. 


The parse service routine uses the IKJPOSIT macro to build a four-word PDE to 
describe an expression value; it has the following format: 


+0 
A pointer to the address string 
+4 +6 +7 
Length3 Flags5 Reserved 
8 


+ +9 +10 
Flags6 Sign Indirect count 
+12 
A pointer to the next expression value PDE ) 
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Pointer to the address string: 
Contains a pointer to the expression value address string. Contains zero if 
this PDE was created due to a switch in indirection symbols. 


Length3: 
Contains the length of the expression value address string. The N is not 
included in this length value. 


Flags5: 
The parse service routine sets bit 0 to indicate the cause of the creation of 
this expression value PDE. The parse service routine sets bit 1 to indicate 
the type of indirect addressing. Bit 1 has no meaning if the indirection 


count is 0. 

| omer ned This expression value PDE created due to + or - sign. 
Ol. oe This expression value PDE created due to ?% or %. 

. oars A 31-bit indirect address is represented. 

| er A 24-bit indirect address is represented. 


XX XXXX Reserved bits. 


Note: Bit 0 and | have the same meaning for MVS 370, but 2 through 16 
are reserved. 


Flags6: 
The parse service routine sets these flags to indicate the type of expression 
value. X‘Q0’ indicates that this PDE was not created for an expression 
value. 


Bit Setting Hex Meaning 


0000 0000 00 This PDE was created due to a change in indirection symbols. 
0000 0100 04 This is a decimal expression value. 
0000 0010 02 This is a hexadecimal expression value. 


Sign: 
Contains the arithmetic sign character used before the expression value 
defined by the next expression value PDE. If the sign field is zero and the 
pointer to the next expression value PDE is non-zero, then the next 
expression value PDE was created due to a switch in indirection symbols 
(2% or %?). If there are no more PDEs, then this field is zero. 


Indirect count: 
Contains a number representing the number of levels of indirect addressing 
within this particular address expression. 


Pointer to the next expression value PDE: 
Contains a pointer to the next expression value PDE if one is present; 
contains X‘FF000000’ if this is the last expression value PDE. 


Each time parse encounters a %? sequence, the current PDE will be completed 
with the 31-bit indirection bit off and the count of 24-bit indirection symbols 
placed in that PDE. A new expression value PDE will be generated in which the 
31-bit indirection bit will be on and the address string address, the decimal value 
bit, and the hexadecimal value bit will all be zero. The number of consecutive 
31-bit indirection symbols will be placed in the latter PDE. 
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Each time parse encounters a ?% sequence, a complementary process will take 
place. Specifically, the 31-bit indirection bit will be on and the count of 31-bit 


indirection symbols will be 


placed in the PDE. A new expression value PDE will 


be generated in which the 31-bit indirection bit will be off and the address string 
address, the decimal value bit, and the hexadecimal value bit will all be zero. The 
number of consecutive 24-bit indirection symbols will be placed in the latter PDE. 


Figure 15-37 illustrates the series of PDEs generated by parse when parse finds an 
address expression containing a mixed sequence of 31-bit and 24-bit indirection 
symbols. The following series of PDEs are generated for 12R%??% + Il6n?, an 
address expression with mixed indirection symbols: 


+16 ; 
A pointer to the address string 
+20 +22 +23 
2 X‘80’' |Reserved 
+24 +25 +26 
X‘20' 0 1 
+28 
A pointer to 1st exp. value PDE 
+32 
Reserved 
(12R%) 


ADDR type PDE 


+4 +6 +7 


0 X'80' |Reserved 


+8 +9 +10 
0 + 1 


A pointer to 3rd exp. value PDE 


(%) 
Expression Value PDE 


+4 +6 +7 
0) X‘40' | Reserved 
+8 +9 +10 
0 0 2 
+12 


A pointer to 2nd exp. value PDE 


(7?) 
Expression Value PDE 


+0 
A pointer to the address string 


+4 +6 +7 
2 X‘'40’ | Reserved 


+8 +9 +10 
X‘04' 0 1 
+12 
X‘FF OO0000’ 


(+16N?) 
Expression Value PDE 


Figure 15-37. Series of PDEs Created for Mixed Sequence of Indirection Symbols 
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USERID: The parse service routine uses the IKJPOSIT macro to build a 
four-word PDE to describe a USERID parameter; it has the following format: 


Pointer to the userid: 
Contains a pointer to the beginning of the userid. Contains zero if the 
userid was omitted. 


Length1: 
Contains the length of the userid. 
Flags1: 
eee, “aa The userid is not present. 
Wises. “apse The userid is present. 


XXX XXxx Reserved bits. 


Pointer to the password: 
Contains a pointer to the beginning of the password. Contains zero if the 
password is omitted. 


Length2: 

Contains the length of the password, excluding the slash. 
Flags2: 

Ose. ‘sis The password is not present. 

Weeks: Gees The password is present. 


.XXX xXxxx Reserved bits. 


UID2PSWD: The parse service routine uses the IKJPOSIT macro to build a 
six-word PDE to describe a UID2PSWD parameter. It has the following format: 
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Pointer to the userid: 
Contains a pointer to the beginning of the userid. It contains zero if the 
userid was omitted. 


Length1: 

Contains the length of the userid. 
Flags1: 

Ons one: Userid is not present. 

Dee > Vanes Userid is present. 


XXX XXXX Reserved. 


Pointer to password 1: 
Contains a pointer to the beginning of password!. It contains zero if the 
password] is omitted. 


Length?2: 

Contains the length of password1, excluding the slash. 
Flags2: 

Os -2as Password 1 is not present. 

| emer Password | is present. 


.XXX XXXX Reserved. 


Pointer to password2: 
Contains a pointer to the beginning of password2. It contains zero if 
password2 is omitted. " 


Length3: 

Contains the length of password2, excluding the slash. 
Flags3: 

Oise: se Password? is not present. 

Tak, stage Password? is present. 


XXX XXXX Reserved. 
CONSTANT: The parse service routine uses the IKJTERM macro to build a 


five-word PDE to describe a CONSTANT parameter. The PDE has the 
. following format: 


+0 +1 +2 
Lengthl Length2 Reserved 
A pointer to the string of digits 
A pointer to the exponent 
+16 
A pointer to the decimal point 
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Lengthl: 
Contains the length of the term entered, depending on the type of parameter 
entered as follows: 


e Fora fixed-point numeric literal, the length includes the digits but not 
the sign or decimal point. 


e For a floating-point numeric literal, the length includes the mantissa 
(string of digits preceding the letter E) but not the sign or decimal point. 


e Fora non-numeric literal, the length includes the string of characters 
but not the apostrophes. 


Length2: 
For a floating-point numeric literal, length2 contains the length of the string 
of digits following the letter E but not the sign. 


Reserved Word Number: 
The reserved word number contains the number of the IKJNAME macro 
that corresponds to the entered name. 


Note: The possible names of reserved words are given by coding a list of 
IKJNAME macros following an IKJRSVWD macro. One IKJNAME 
macro is needed for each possible name. If the name entered does not 
correspond to one of the names in the IKJNAME macro list then this field 
is set to zero. 


Flags: 
Byte 1: 


The parameter is missing. 
Lay. ged The parameter is present. 
Seamer Constant. 
Ps mere Variable. 
tele sadee Statement number. 
i ae Fixed-point numeric literal. 
lL. Non-numeric literal. 
ma Figurative constant. 
me Floating-point numeric literal. 


Qiax, -uan3 Sign on constant is either plus or omitted. 

Tegie vee Sign on constant is minus. 

Sign on exponent of floating-point numeric literal is either plus or omitted. 
se Sign on exponent of floating-point numeric literal is minus. 

he Bue Decimal point is present. 

..X Xxxx Reserved bits. 


— oc 


Pointer to the string of digits: 
Contains a pointer to the string of digits, not including the sign if entered. 
Contains zero if a constant type of parameter is not entered. 


Pointer to the exponent: 


Contains a pointer to the string of digits in a floating-point numeric literal 
following the letter E, not including the sign if entered. 
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Pointer to the decimal point: 


Contains a pointer to the decimal point in a fixed-point or floating-point } 
numeric literal. If a decimal point is not entered, this field is zero. ) 


STATEMENT NUMBER: The parse service routine uses the IKJTERM macro 


to build a five-word PDE to describe a STATEMENT NUMBER parameter. 
The PDE has the following format: 


+0 +1 +2 +3 
Length! Length2 Length3 Reserved 


A pointer to the program-id 

A pointer to the line number 
+16 

A pointer to the verb number 


Length]: 


Contains the length of the program-id specified but does not include the 
following period. Contains zero if the program-id is not present. 


Length2: 

Contains the length of the line number entered but does not include the 

delimiting periods. Contains zero if the line number is not present. \ 
Length3: 


Contains the length of the verb number entered but does not include the 
preceding period. Contains zero if the verb number is not present. 


Flags: 

Byte 1: 
Dees. fess The parameter is missing. 
Tees cats The parameter is present. 
ee Constant. 
eer Variable. 
eal pe Statement number. 

xxxx Reserved. 
Byte 2: 


XXXX XXXx Reserved. 


Pointer to the program-id: 


Contains a pointer to the program-id, if entered. Contains zero if not 
present. 


Pointer to the line number: 


Contains a pointer to the line number, if entered. Contains zero if not 
present. 


J 
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Pointer to the verb number: 


( Contains a pointer to the verb number, if entered. Contains zero if not 
present. 


VARIABLE: The parse service routine builds a five-word PDE (when using the 
IKJTERM macro) to describe a VARIABLE parameter. The PDE has the 
following format: 


A pointer to the data-name 


+5 +6 
Length! Reserved Flags Reserved 


A pointer to the PDE for the first qualifier 


A pointer to the program-id name 


+17 +18 +19 
Length2 Number of Number of Reserved 
Qualifiers Subscripts 


Pointer to the data-name: 
Contains a pointer to the data-name. If a program-id qualifier precedes the 
data-name, this pointer points to the first character after the period of the 
program-id qualifier. 


Length1: 
WY Contains the length of the data-name. 
Flags: 
Byte 1: 
The parameter is missing. 

Tous “ge The parameter is present. 

hee, st Constant. 

oe) ees Variable. 

| Statement number. 


xxxx Reserved. 


Pointer to the PDE for the first qualifier: 
Contains a pointer to the PDE describing the first qualifier of the 
data-name, if any. This field contains X‘FF000000’ if no qualifiers are 
entered. 


Note: The format of the PDE for a data-name qualifier follows this 
description. 


Pointer to the program-id name: 


Contains a pointer to the program-id name, if entered. This field contains 
zero if the optional program-id name is not present. 


Length2: 


Contains the length of the program-id name, if entered. Contains zero if the 
C optional program-id name is not present. 
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Number of Qualifiers: 
Contains the number of qualifiers entered for this data-name. (For 
example, if data-name A of B is entered, this field would contain 1.) 


Number of Subscripts: 
Contains the number of subscripts entered for this data-name. (For 
example, if data-name A(1,2) is entered, this field would contain 2.) 


The format of a data-name qualifier 1s: 


A pointer to the data-name qualifier 


+5§ 
Reserved Reserved 


A pointer to the PDE for the next qualifier 


Pointer to the data-name qualifier: 
Contains a pointer to the data-name qualifier. 


Length: 
Contains the length of the data-name qualifier. 


Flags: 


XXXX XXXX Reserved. 


Pointer to the PDE for the next qualifier: 
Contains a pointer to the PDE describing the next qualifier, if any. This 
field contains X‘FFO00000’ for the last qualifier. 


RESERVED WORD: The parse service routine uses the IKJRSVWD macro to 
build a two-word PDE (using the IKJRSVWD macro instruction) to describe a 
RESERVED WORD parameter. The PDE has the following format: 


Note: This PDE is not used when the IKJRSVWD macro instruction is chained 
from an IKJTERM macro instruction. In this case, the 

reserved-word number is returned in the CONSTANT parameter PDE built by 
the IKJTERM macro instruction. 


Reserved-word number: 
The reserved-word number contains the number of the IKJNAME macro 
instruction that corresponds to the entered name. 


Note: The possible names of reserved-words are given by coding a list of 
IKJNAME macros following an IKJRSVWD macro. One IKJINAME 
macro is needed for each possible name. If the name entered does not 
correspond to one of the names in the IKJNAME macro list, this field is set 
to zero. 


Flags: 
Bytel: 


Olin Ans The parameter is missing. 
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| eae The parameter is present. 
XXX XXXX Reserved. 


EXPRESSION: The parse service routine uses the IKJOPER macro to build a 
two-word PDE to describe an EXPRESSION parameter. The PDE has the 
following format: 


Reserved 


Reserved Reserved 


Olas, «tee The entire parameter (expression) is missing. 
1... ....7 The entire parameter (expression) is present. 
.XXX XXXX Reserved. 


IKJIDENT PDE: The parse service routine uses the IKJIDENT macro 
instruction to build a two-word PDE to describe a non-delimiter-dependent 
positional parameter; it has the following format: 


A pointer to the positional parameter 


Reserved 


Pointer to the positional parameter: 
Contains a pointer to the beginning of the positional parameter. If INTEG 
was specified on the IKJIDENT macro instruction, this will contain a 
pointer to a fullword binary value. 


Contains zero if the positional parameter is omitted. 


Length: 

Contains the length of the positional parameter. 
Flags: 

Os. 26 The parameter is not present. 

Ds: “asew The parameter is present. 


XXX XXXX Reserved bits. 
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Effect of List and Range Options on PDE Formats 


The formats of the IKJPARMD mapping DSECT and of the PDEs built by the 
parse service routine are affected by the options you specify in the parse macro 
instructions, as well as by the type of parameter specified. If you specify the 


LIST or the RANGE options in the parse macro instructions describing positional 
parameters, the IKJPARMD DSECT and the PDEs returned by the parse service 


routine are modified to reflect these options. 


LIST: The LIST option may be used with the following positional parameter 
types: 


USERID 

DSNAME 

DSTHING 

ADDRESS 

VALUE 

CONSTANT 

VARIABLE 
STATEMENT NUMBER 
HEX 

INTEG 

CHAR 

Any non-delimiter-dependent positional parameter 


If you specify the LIST option in the parse macro instructions describing the 
above listed positional parameter types, the parse service routine allocates an 
additional word for the PDE created to describe the positional parameter. This 
word is allocated even though a list may not actually be entered by the terminal 
user. Ifa list is not entered, this word is set to X‘FFOQ00000’. If a list is entered, 
the additional word will be used to chain the PDEs created for each element 
found in the list. Each additional PDE has a format identical to the one 
described for that parameter type within the IKJPARMD DSECT. Since the 


number of elements in a list is variable, the number of PDEs created by the parse 


service routine is also variable. The chain word of the PDE created for the last 
element of the list is set to X‘FFO00000’. 
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Figure 15-38 shows the PDL returned by the parse service routine after three 
positional parameters have been entered. In this case, the first two parameters, a 
USERID and a STRING parameter, had been defined as not accepting lists. The 
third parameter, a VALUE parameter, had the LIST option coded in the 
IKJPOSIT macro instruction that defined the parameter syntax. The VALUE 
parameter was entered as a two-element list. 


PDL - Mapped by IKJPARMD DSECT 


PDL Header 


USERID PDE 


STRING PDE 


VALUE PDE 
(First element of a two element list) 
Chain Word 


VALUE PDE 
(Last element of a two 
element list) 


Figure 15-38. A PDL Showing PDEs Describing a List 


RANGE: The RANGE option may be used with the following positional 
parameter types: 


HEX (X*’ only) 

ADDRESS 

VALUE 

CONSTANT 

VARIABLE 

STATEMENT NUMBER 

INTEG 

Any non-delimiter-dependent positional parameter 


If you specify the RANGE option in the parse macro instructions describing the 
above listed positional parameter types, the parse service routine builds two 
identical, sequential PDEs within the PDL returned to the calling routine. Space 
is allocated for the second PDE even though a range may not actually be supplied 
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by the terminal user. If a range is not supplied, the second PDE 1s set to zero. 
The flag bit which is normally set for a missing parameter will also be zero in the 
second PDE. 


Figure 15-39 shows the PDL returned by the parse service routine after two 
positional parameters have been entered. In this case, the first parameter is a 
USERID parameter and the second parameter is a VALUE parameter that had 
the RANGE option coded in the IKJPOSIT macro instruction that defined the 
parameter.syntax. For this example, the VALUE parameter was not entered as a 
range, and, consequently, the second PDE 1s set to zero. 


PDL - Mapped by IKJPARMD DSECT 


PDL Header 


USERID PDE 


VALUE PDE 
(May be entered as a Range) 


VALUE PDE built to receive second element of Range. 
(Parameter was not entered as a Range) 


Figure 15-39. A PDL Showing PDEs Describing a Range 


Combining the LIST and RANGE Options: If you specify both the LIST and 
RANGE options in a parse macro instruction describing a positional parameter, 
the parse service routine builds two identical PDEs within the PDL returned to 
the calling routine. Both of these PDEs are formatted according to the type of 
positional parameter described. These two PDEs describe the RANGE. An 
additional word is appended to the second PDE for the purpose of chaining any 
additional PDEs built to describe the LIST. 


Figure 15-40 shows this general format. 
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PDL - Mapped by IKJPARMD DSECT 


aaa 
Ld (Parameter may be entered as a range) 
+ parameter may be entered os is) 


Identical PDE 


Figure 15-40. A PDL Showing PDEs Describing LIST and RANGE Options 


If you have specified both the LIST and the RANGE options in the parse macro 
instruction describing a positional parameter, the user at the terminal has the 
option of supplying a single parameter, a single range, a list of parameters, or a 
list of ranges. The construction of the PDL returned by the parse service routine 
can reflect each of these conditions. 


Figure 15-41 shows the PDL returned by the parse service routine if the user 
enters a single parameter. 
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PDL - Mapped by IKJPARMD DSECT 


PDL Header 


PDE - Filled in 


Ome — 


0 
Identical PDE - Zeroed 
F 0 0 0 0 0 0 


F Chain Word 


Figure 15-41. PDL - LIST and RANGE Acceptable, Single Parameter Entered 
As Figure 15-41 further shows, the second PDE and the chain word are both set 
to zero by the parse service routine, if the LIST and RANGE options were coded 
in the macro instruction describing the parameter, but the user entered a single 


parameter. 


Figure 15-42 shows the PDL returned by the parse service routine if the user 
enters a single range of the form: 


parameter:parameter 


PDL - Mapped by IKJPARMD DSECT 


PDL Header 


PDE - Filled in 


Identical PDE - Filled in 


Chain Word 


Figure 15-42. PDL - LIST and RANGE Acceptable, Single Range Entered 


As Figure 15-42 further shows, both PDEs are filled in to describe the single 
RANGE parameter entered by the user. The chain word is set to X‘FF0O00000’ to 
indicate that there are no elements chained onto this one; that is, the parameter 
was not entered in the form of a LIST. 
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Figure 15-43 shows the format of the PDL returned by the parse service routine if 
the user enters a list of parameters in the form: 


(parameter,parameter,...) 


PDL - Mapped by IKJPARMD DSECT 


PDL Header 


PDE - Filled in 


Identical PDE - Zeroed 


PDE - Filled in 


Identical PDE = Zeroed 


Chain Word 


Figure 15-43. PDL - LIST and RANGE Acceptable, LIST Entered 


As Figure 15-43 further shows, each of the first PDEs and the chain word 
pointers are filled in by the parse service routine to describe the list of parameters 
entered by the user. The second, identical PDEs are zeroed to indicate that the 
parameter was not entered in the form of a range. 


The last set of PDEs on the chain will contain X‘FF000000’ in the chain word to 
indicate that there are no more PDEs on that particular chain. 
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The PDL created by the parse service routine to describe a parameter entered as a 

list of ranges is similar to the one created to describe a list. The difference is that 
the second, identical PDEs are also filled in by the parse service routine to J 
describe the ranges entered. 


Figure 15-44 further shows the format of the PDL returned by the parse service 
routine if the user enters a list of ranges in the form: 


(parameter:parameter, parameter:parameter,...) 


PDL = Mapped by IKJPARMD DSECT 


PDL Header 


ae SF 
nS ni 


Chain Word 


PT UE eee 


Chain Word 


Figure 15-44. PDL - LIST and RANGE Acceptable, List of Ranges Entered 
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As Figure 15-44 shows, each of the PDEs and each of the second, identical PDEs 
are filled in by the parse service routine to describe the ranges entered. The chain 
words are also filled in to point down through the list of parameters entered. 


The last set of PDEs on the chain will contain X‘FFO00000’ in the chain word to 
indicate that there are no more PDEs on that particular chain. 


The PDE Created for a Keyword Parameter 


‘Parse builds a halfword (2-byte) PDE to describe a keyword parameter; it has the 


following format: 


+0 


Number 
+2 


Number: 
You describe the possible names for a keyword parameter to the parse 
service routine by coding a list of IKJNAME macro instructions directly 
following the IKJKEYWD macro instruction. One IKJNAME macro 
instruction must be executed for each possible name. 


The parse service routine places into the PDE the number of the IKJNAME 
macro instruction that corresponds to the keyword name entered. 


If the keyword is not entered, and you did not specify a default in the 
IKJKEYWD macro instruction, the parse service routine places a zero into 
the PDE. 


Additional Facilities Provided by Parse 


Translation to Uppercase 


Insertion of Default Values 


The parse service routine, in addition to determining if command parameters are 
syntactically correct, provides the following services which may be selected by the 
calling routine. 


Positional parameters are ordinarily translated to uppercase unless the calling 
routine specifies ASIS in the IKJPOSIT or IKJIDENT macro instructions. The 
first character of a value parameter, the type-character, is always translated to 
uppercase, however. The string that follows the type character is translated to 
uppercase, unless ASIS is coded in the describing macro instructions. 
Double-byte character set strings in MVS/XA are an exception to this rule. 
Regardless of whether or not you specify ASIS, the contents of the double-byte 
character set string is not translated to upper case. 


Positional parameters (except delimiter and space) and keyword parameters may 
have default values. These default values are indicated to the parse service 
routine through the DEFAULT = operand of the IKJPOSIT, IKJTERM, 
IKJOPER, IKJRSVWD, IKJIDENT, and IKJKEYWD macro instructions. 
When a positional or a keyword parameter is omitted, for which a default value 
has been specified, the parse service routine inserts the default value. 
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The parse service routine also inserts the default value you specified if a 
parameter is invalid and the terminal user enters a null line in response to a 
prompt. 


Passing Control to a Validity Checking Routine 


You can provide a validity checking routine to do additional checking on a 
positional parameter. Each positional parameter can have a unique validity 
checking routine. Indicate the presence of a validity checking routine by coding 
the entry point address of the routine as the VALIDCK = operand in the 
IKJPOSIT, IKJTERM, IKJOPER or IKJIDENT macro instructions. 


The parse service routine can call validity checking routines for the following 
types of positional parameters: 


HEX 

VALUE 

ADDRESS 

QSTRING 

USERID 

DSNAME 

DSTHING 

CONSTANT 

VARIABLE 
STATEMENT NUMBER 
EXPRESSION 
JOBNAME 

INTEG 

Any non-delimiter-dependent parameters 


The validity check exit is taken after the parse service routine has determined that 
the parameter is non-null and syntactically correct. If a dsname or userid 
parameter is entered with a password, parse takes the validity check exit after first 
parsing both the userid or dsname and the password. If the terminal user enters a 
list, the validity check routine is called as each element in the list 1s parsed. Ifa 
range is entered, the parse service routine calls the validity check routine only 
after both items of the range are parsed. 


Parse invokes all validity checking exit routines in the same addressing mode in 
which parse is invoked. Note that if a SYNCH macro 1s used to invoke parse, 
the addressing mode of the caller may be different than that in which parse 1s 
invoked. 


When control is passed from the parse service routine to a validity checking 
routine, the parse service routine uses standard linkage conventions. The validity 
check routine must save parse’s registers and restore them before returning control 
to the parse service routine. The parse service routine builds a three-word 
parameter list and places the address of this list into register 1 before branching to 
a validity checking routine. This three-word parameter list has the format shown 
in Figure 15-45. 


15-84 TSO/E Guide to Writing a TMP or a CP 


sige | mow | comes 


PDEADR The address of the parameter descriptor entry (PDE) built by parse for 
this syntactically correct parameter. 


USERWORD | The address of the user work area. This is the same address you 
supplied to the parse service routine in the parse parameter list. 


VALMSG Initialized to X‘00000000’ by parse. A user-provided validity checking 
routine can place the address of a second level message in this field. 


Figure 15-45. Format of the Validity Check Parameter List 


Your validity checking routines must return a code in general register 15 to the 
parse service routine. These coces inform the parse service routine of the results 
of the validity check and determine the action that parse should take. 

Figure 15-46 shows the return codes, their meaning, and the action taken by the 
parse service routine. 


Retur 


The parameter is valid. No additional processing is performed on this parameter 
by the parse service routine. 


The parameter is invalid. The parse service routine writes an error message to the 
terminal and prompts for a valid parameter. 


The parameter is invalid. The validity checking routine has issued an error 
message; parse prompts for a valid parameter. 


The parameter is invalid; The parse service routine stops all further syntax 
syntax checking cannot checking and returns to the calling routine. 
continue. 


Figure 15-46. Return Codes from a Validity Checking Routine 


If the parse service routine receives a return code of 4 or 8, the new data entered 
in response to the prompt is parsed as if it were the original data and control is 
again passed to the validity check routine. This cycle continues until a valid 
parameter is obtained. 


Insertion of Keywords 


Some keyword parameters may imply other keyword parameters. You may 
specify that other keywords are to be inserted into the parameter string when a 
certain keyword is entered. Use the INSERT operand of the IKJNAME macro 
instruction to indicate that a keyword or a list of keywords is to be inserted 
following the named keyword. The inserted keywords are processed as if they 
were entered from the terminal. 


Issuing Second Level Messages 


You may supply second level messages to be chained to any prompt message 
issued for a positional parameter (keyword parameters are never required). Use 
the HELP operand of the IKJPOSIT, IKJITERM, IKJOPER, IKJRSVWD or 
IKJIDENT macro instructions to supply these second level messages to the parse 
service routine. You can supply up to 255 second level messages for each 
positional parameter. One second level message is issued each time a question 
mark is entered from the terminal. If a question mark is entered and no second 
level messages were provided, or they have all been issued in response to previous 
question marks, the terminal user is notified that no help 1s available. 
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Prompting 


If a user-provided validity checking routine returns the address of a second level 
message to the parse service routine, that second level message or chain will be 
written out in response to question marks entered from the terminal. The original 
second level chain, if one was present, is deleted. 


The format of these second level messages is the same as the HELP second level 
message portion of the PCE for the macro from which the validity checking 
routine received control. 


The parse service routine prompts the terminal user if the command parameters 
found are incorrect or if required parameters are missing. It allows the terminal 
user to enter a missing parameter or correct an incorrect one without having to 
reenter the entire command. The parse service routine prompts, and the terminal 
user must respond, in the following situations: 


1. A userid or dsname was entered with a slash but without a password. 
2. A parameter is syntactically invalid. 


3. A keyword is ambiguous, that is, it is not clear to the parse service routine 
which keyword of several similar ones is being entered. 


4. A required positional parameter is missing. The requirement for a particular 
positional parameter and the prompting message to be issued if that 
parameter is not present, are specified to the parse service routine through the 
PROMPT operand of the IKJPOSIT, IKJTERM, IKJOPER, IKJRSVWD, 
and IKJIDENT macro instructions. The parse service routine puts out the 
prompting message supplied in the macro instruction. 


5. A validity check exit indicates that a parameter is invalid. 


There are a number of rules that govern the processing of responses entered from 
the terminal after a prompt. 


1. All of the new data entered is parsed before the scan of the original command 
is resumed. 


2. Unless otherwise stated in the command syntax definition, the new parameter 
is entered as it is entered in the original command. See “Command 
Parameter Syntax” for exceptions to this rule. 


3. In general, additional parameters may be entered along with the data 
prompted for. It must be kept in mind, however, that all of the new data 
entered 1s parsed before the scan of the material in the original command 
buffer is resumed. A problem could occur in a situation where a command is 
entered followed by two positional parameters and a keyword, and the first 
positional parameter is invalid. The parse service routine issues a prompt for 
the first positional parameter. When the user at the terminal reenters that 
first positional parameter, it would be invalid to enter additional keywords 
along with it. The additional keywords would be scanned before the second 
positional parameter and an error condition would result when the parse 
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service routine returned to the original command buffer and found a 
positional parameter. 


Note that if the parameter prompted for is within a subfield, only parameters 
valid within that subfield may be entered along with the parameter prompted 
for. 


4. In general, a null response 1s acceptable only for optional parameters. 
However, if a null response is entered for an optional parameter that has a 
default, parse inserts the default. If a prompt for a required parameter is 
answered by a null response from the terminal, parse reissues the prompt 
message. The parse service routine continues prompting until a correct 
parameter is entered. The terminal user can request termination by entering 
an attention. 


Parse will always accept a null response to a prompt for a password, whether 
or not the dsname or userid parameters are required. It is the responsibility 
of the routine using the parse service routine to ensure that the correct 
password was entered if one was required, by checking the password pointed 
to by the PDE returned by the parse service routine. 


5. Ifa required parameter which may be entered in the form of a list is missing, 
or if 1t was entered as a single parameter (not as a list), and that single 
parameter is incorrect, parse will not accept a list after the prompt. The user 
at the terminal must enter a single parameter. 


If, however, the item was entered as a list but an item within the list is 
invalid, the parse service routine accepts one or more parameters after the 
prompt. The parse service routine considers these newly entered parameters 
to be part of the original list. Parameters that are not valid in the list may be 
entered from the terminal in response to this prompt. 


If the last item in a list 1s found to be invalid, parse only accepts one 
parameter after a prompt. 


6. If the parse service routine determines that a parameter is invalid, the invalid 
portion of the parameter is indicated in the error message. The remainder of 
the parameter is not yet parsed. The user must reenter as much of the invalid 
parameter as was indicated in the error message. This situation often occurs 
if a dsname parameter or userid parameter is entered with blanks between the 
dsname or userid and the password. The dsname or userid may be invalid 
but the password is still good and will be parsed after a new dsname or userid 
is entered in response to the prompt. 


The parse service routine always attempts to obtain syntactically correct 
parameters before returning to the calling routine. However, this is not always 
possible. The terminal user may have requested that no prompt messages be sent 
to the terminal, or the command being parsed may have come from a procedure. 
In these cases, an error message is issued and a code is returned to the calling 
routine indicating that a correct command could not be obtained. Any second 
level messages that would ordinarily be appended to the request for new data are 
appended to the error message. 
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Examples of Using the Parse Service Routine 


Example 1 


This example shows how the parse macro instructions could be used within a 
command processor to describe the syntax of an EDIT command to the parse 
service routine. 


The sample EDIT command we are describing to the parse service routine has the 
following format: 


dsname 


PLI |(|/number |/number CHARGBO | ) 
2, a2 CHAR48 


FORT 
ASM 

TEXT 
DATA 


SCAN 
NOSCAN 


NUM 
NONUM 


BLOCK (number ) 
BLKSIZE (number) 


LINE (number ) 


Figure 15-47 shows the sequence of parse macro instructions that would describe 
the syntax of this EDIT command to the parse service routine. 
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Figure 15-47. Coding Example 1 - Using Parse Macros to Describe Command Parameter Syntax 


The parse macro instructions shown in Figure 15-47 perform two distinct 
functions when executed: 


1. Build the parameter control list describing the syntax of the EDIT command 
parameters. The PCL is used by the parse service routine during its scan of 
the parameters within the command buffer. 


2. Create the IKJPARMD DSECT (defaulted to on the IKJPARM macro 
instruction) that you use to map the parameter descriptor list returned by the 


parse service routine after it scans the parameters within the command buffer. 


Your code never refers to the PCL; it is used only by the parse service routine. 
Therefore, it is not shown in the example. 
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Figure 15-48 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 


YPE, ps: ||| wii BRER 

SseAWw |i itis tt | mw TTT TTT TT 

777 OR ee ee 
x RRS eH 


ack ||| si |i Thy 
puKis Bel [bis loa 
eS 


pLrcozis | bs || 
perncoe2 | bs | | 
pc treee pet 


| 
{ 


BL KWubd | | sl | 


Figure 15-48. An IKJPARMD DSECT (Example 1) 


If a terminal user entered the above described EDIT command in the form: 


edit sysfile/x pl1(3) nonum block 


the parse service routine would prompt for the blocksize as follows: 


ENTER BLOCKSIZE 


The user at the terminal might respond with: 


160 


The parse service routine would then complete the scan of the command 
parameters, build a parameter descriptor list (PDL), place the address of the PDL 
into the fullword pointed to by the fifth word of the parse parameter list, and 
return to the calling program. 


The calling routine uses the address of the PDL as a base address for the 
IKJPARMD DSECT. 


Figure 15-49 shows the PDL returned by the parse service routine. The symbolic 
addresses within the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply, and the meanings of the fields within 

the PDL are explained to the nght of the PDL. 
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1K JPARMD Description of 
DSECT Field Contents 
IK JPARMD 


PDL Header. Used only by 


Ce 


Pointer to SYSFILE Data Set Name 


a | 


Pointer to X Password 


No member name 


TYPE, SCAN PL1, NOSCAN 
NUM, BLOCK NONUM, BLOCK 
LINE LINE not specified 


PLITYPE | Umsed | CHAR60 is the default 


Figure 15-49. The IKJPARMD DSECT and the PDL (Example 1) 
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Example 2 


This example shows how the parse macro instructions could be used to describe 
the syntax of a sample AT command that has the following syntax: 


COMMAND OPERANDS 


stmt 
(stmt-1,stmt-2,...) ? (cmd,chain) COUNT(integer) 
stmt-3:stmt-4 


Figure 15-50 shows the sequence of parse macro instructions that describe this 
sample AT command to the parse service routine. 
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Figure 15-50. Coding Example 2 - Using Parse Macros to Describe Parameter Syntax 


The parse macro instructions shown in Figure 15-50 perform two distinct 
functions when executed: 


1. Build the parameter control list describing the syntax of the command 
parameters. This PCL is then used by the parse service routine during its 
scan of the parameters in the command buffer. 


2. Create the IKJPARMD DSECT that you use to map the parameter 
descriptor list. The PDL is returned by the parse service routine after it scans 
the parameters in the command buffer. 


Note: Your code never refers to the PCL; it is used only by the parse service 
routine. Therefore, the parameter control list is not shown in the example. 


Figure 15-51 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 
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Figure 15-51. An IKJPARMD DSECT (Example 2) 


In this example, if the terminal user entered the above described command 
incorrectly like this: 


at 200/3 (list all) count(a) 


the parse service routine would prompt the terminal user with the message: 


INVALID STATEMENT NUMBER, 200/3 
REENTER 


The user might respond with: 


200.3 


the parse service routine would then prompt the user with: 


INVALID COUNT, a 
REENTER 


The user might respond with: 


3 


This sequence resulted in the syntactically correct command of: 


at 200.3 (list all) count(3) 


The parse service routine would then build a parameter descriptor list (PDL) and 
place the address of the PDL into the fullword pointed to by the fifth word of the 
parse parameter list. 


The parse service routine then returns to the caller and the caller uses the address 
of the PDL as a base address for the IKJPARMD DSECT. 


Figure 15-52 shows the PDL returned by the parse routine. The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields within the 
PDL is shown on the right. 
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IK JPARMD 
DSECT 


STMTPCE 


POSITPCE 


KEYPCE 


IDENTPCE 


ee 
fo 
PDE Offset 


3 


Pointer to 200 


Pointer to 3 


X 'FFO00000' 


Pointer to LIST in string 


Pointer to 3 


Figure 15-52. The IKJPARMD DSECT and the PDL (Example 2) 


Example 3 


Description of 
Field Contents 


PDL Header, used only by 
IKJRLSA 


Lengths (program -id, line no. 
and verb no. ) 


Parameter is present 
No program - id 
Line number 


Verb number 


Double PDE for RANGE option, 
but not entered 


LIST option not entered 

First character after ) 
Length, parameter is present 
First keyword 

Subfield 


Length, parameter is present 


This example shows how the parse macro instructions could be used to describe 
the syntax of a sample LIST command that has the following syntax: 
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COMMAND OPERANDS 
symbol PRINT(symbol) 


ao 


Meech e 


e 


EF. ' |p 


jE 
aa 
eee 


Saisie] pele. 


Figure 15-53 shows the sequence of parse macro instructions that describe this 
sample LIST command to the parse service routine. 


\A a, 


Figure 15-53. Coding Example 3 - Using Parse Macros to Describe Parameter Syntax 


The parse macro instructions shown in Figure 15-53 perform two distinct 
functions when executed: 


1. Build the parameter control list describing the syntax of the command 
parameters. This PCL is then used by the parse service routine during its 
scan of the parameters in the command buffer. 


2. Create the IKJPARMD DSECT that you use to map the parameter 
descriptor list. The PDL is returned by the parse service routine after it scans 
the parameters in the command buffer. 


Note: Your code never references the PCL; it is used only by the parse service 
routine. Therefore, the parameter control list for the example is not shown. 


Figure 15-54 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 


a) oh 
} ‘ 


Figure 15-54. An IKJPARMD DSECT (Example 3) 


In this example, if the terminal user entered the above described command 
incorrectly like this: 


list a of 1 in 3({1) print(d) 


the parse service routine would prompt the terminal user with: 


INVALID SYMBOL, a...1 in 3(1) 
REENTER 
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The user might respond with: 


a of b in 3(1) 


the parse service routine would then prompt with: 


INVALID SYMBOL, a...3(1) 
REENTER 


The user might respond with: 


a of b in c(1) 


This sequence resulted in the syntactically correct command of: 


list a of b in c(1) print(d) 


The parse service routine would then build a parameter descriptor list (PDL) and 
place the address of the PDL into the fullword pointed to by the fifth word of the 
parse parameter list. 


The parse service routine then returns to the caller and the caller uses the address 
of the PDL as a base address for the IKJPARMD DSECT. 


Figure 15-55 shows the PDL returned by the parse service routine. The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields within the 
PDL is shown on the right. 
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IK JPARMD 
DSECT 


Description of 
Field Contents 


PARSED ree } PDL Header = Used only by 
sce | [tf 
Pointer to | | Subscript 
No exponent 


No decimal point 


| 


X '0000' 
2nd element in subscript ~ 
( Not entered ) 


a 
Hit 
: 


X'0000' 
3rd element in subscript ~ 
(Not entered } 


KEYPCE 
PRINTSUB Pointer to d Data = name 


p= | xm 


First keyword 


Length, parameter, variable 


No qualifiers 


No program = id 


* 


No length, qualifier, or subscript 


Pointer to b First qualifier 


Pointer to next qualifier Next qualifier 


(First 
Qualifier) 


Length, parameter, variable 


+ —__>. 


Second qualifier 


ete) (dat premetr, vercle 


X 'FFQ00000' End of qualifiers 


*Note: May not be contiguous in storage at this point. 


( Figure 15-55. The IKJPARMD DSECT and the PDL (Example 3) 
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Example 4 


This example shows how the parse macro instructions could be used to describe 
the syntax of a sample WHEN command that has the following syntax: 


COMMAND OPERANDS 


WHEN addr (subcommand chain) 
expression 


Figure 15-56 shows the sequence of parse macro instructions that describe this 
sample WHEN command to the parse service routine. 


essoln’ OA, 
DPERNDZ + s yb: 


kJ 


Figure 15-56. Coding Example 4 - Using Parse Macros to Describe Parameter Syntax 


The parse macro instructions shown in Figure 15-56 perform two distinct 
functions when executed: 


1. Build the parameter control list describing the syntax of the command 
parameters. This PCL is then used by the parse service routine during its 
scan of the parameters in the command buffer. 


2. Create the IKJPARMD DSECT that you use to map the parameter 
descriptor list. The PDL is returned by the parse service routine after it scans 
the parameters in the command buffer. 


Note: Your code never references the PCL; it is used only by the parse service 
routine. Therefore, the parameter control list for this example is not shown. 


Figure 15-57 shows the IKJPARMD DSECT created by the expansion of the 
parse macro instructions. 
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Figure 15-57. An IKJPARMD DSECT (Example 4) 


In this example, if the terminal user entered the above described command 
incorrectly like this: 


when (a) (list b) 


the parse service routine would prompt the terminal user with: 


ENTER OPERATOR 


The user might then respond: 
eq 
the parse service routine would then prompt with: 


INVALID EXPRESSION, (a eq) 
REENTER 


The user might respond then with: 


(a eq b) 


This sequence resulted in a syntactically correct command of: 


when (a eq b) (list b) 


The parse service routine would then build a parameter descriptor list (PDL) and 
place the address of the PDL into the fullword pointed to by the fifth word of the 
parse parameter list. 


The parse service routine then returns to the caller and the caller uses the address 
of the PDL as a base address for the IKJPARMD DSECT. 


Figure 15-58 shows the PDL returned by the parse service routine. The symbolic 
addresses of the IKJPARMD DSECT are shown to the left of the PDL at the 
points within the PDL to which they apply. A description of the fields within the 
PDL is shown on the right. 
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IK JPARMD 
DSECT 


PARSE3 


| 


OPERATOR 


SYMBOL2 


= ee 
X 'FFO00000' 


LASTONE Pointer to LIST 
ae 


Figure 15-58. The IKJPARMD DSECT and PDL (Example 4) 
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Description of 
Field Contents 


PDL Header - Used only by 
IKJRLSA 


Parameter is present 

First operand 

Length, parameter is present 
No qualifiers 


No program = id 


No lengths for program - id, 
subscripts, or qualifiers 


First keyword entered 
Parameter is present 

Second operand 

Length, parameter, variable 
No qualifiers 


No program - id 


No lengths for program - id, 
subscripts or qualifiers 


(Address - Not entered ) 


Subcommand 


Length, parameter is present 


Return Codes from the Parse Service Routine 


C When it returns to the program that invoked it, the parse service routine provides 
one of the following return codes in general register 15: 


Code Meaning 


decimal 

0 Parse completed successfully. 

4 The command parameters were incomplete and parse was unable to prompt. 

8 Parse did not complete. An attention interruption occurred during parse processing. 

12 The parse parameter block contains invalid information. 

16 Parse issued a GETMAIN and no space was available. 

20 A validity checking routine requested termination. 

24 Conflicting parameters were found on the IKJTERM, IKJOPER, or IKJRSVWD macro 
Instruction. 

28 The termina] has been disconnected. 


No error message is needed for return codes 4 and 20. The parse service routine 
issues a message before returning a code of 4 and the validity checking routine 
issues an error message before it requests termination. The GNRLFAIL routine 
can be invoked to issue meaningful error messages for the other parse return 
codes. See “GNRLFAIL/VSAMFAIL Routine (IKJEFF19)” in this book. 
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Chapter 16. Catalog Information Routine (IKJEHCIR) 


The catalog information routine retrieves information from the system catalog. 
This information may include data set name, index name, control volume address, 
or volume ID. The information may be requested from a specific user catalog, or, 
if no catalog was specified, the system default catalog search is used. An entry 
code indicates the requested kind of information as follows: 


e The next level qualifiers for a name 


e All names having the same name as the high-level qualifier and the data set 
type associated with each name 


@ The volume serial numbers and device types associated with a name 
The requester can also ask for combinations of the information above. 


The catalog information routine resides in SYS1.LPALIB and executes with the 
protection key of the caller. 


IKJEHCIR may be invoked in either 24- or 31-bit addressing mode. However, all 
input passed to IKJEHCIR must reside below 16 Mb in virtual storage. 
IKJEHCIR executes in 24-bit addressing mode and returns control in the same 
addressing mode in which it is invoked. 


The catalog information routine parameter list (CIRPARM) is shown in 
Figure 16-1. 


risa | Commmoe Menning 


CIROPT Entry code/options used. See Figure 16-2. 
Reserved. 


CIRLOCRC Locate return code. 


CIPSRCH 


Address of the search argument. This search argument is a userid and 
a data set name which are names of catalog index levels. 


Address of the volume ID of CVOL. If not given, SYSRES is 
assumed. 


CIRCVOL 


CIRWA 
CIRSAVE 
CIRPSWD 


Address of the user work area. See Figure 16-3 for the user work area. 


Address of a 72-byte save area. 


Address of an 8-byte password or zero. 


Figure 16-1. Catalog Information Routine Parameter List (CIRPARM) 
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The CIROPT values and data returned are shown in Figure 16-2. 


Data Required 


Move the data set names having one 8-byte qualifiers are moved into the 
more level of qualifier above what the user’s work area. 
user specified. 


45-byte data set names are moved to 
the user work area. 


Move all data set names to the user 
work area. 


Volume information is moved to the 
user work area. See Figure 16-4 for 
volume information format. 


Get a volume associated with a given 
data set name. 


Get the next level data set name and 
volume information. 


45-byte data set name and volume 
information is moved to the user work 
area. 


Get all level data set names and 
volume information. 


45-byte data set name followed by 
volume information is moved to the 
user work area for all levels. 


Figure 16-2. Data Returned from Valid CIROPT Values 


Note: For codes X‘02’, X‘05’, and X‘06’, the first byte of the field contains one of 
the following data set types: 


V for volume 

C for cluster 

G for alternate index 
R for path 

F for FREE 

Y for upgrade 

B for GDG base 

X for alias name 

P for page space 

M for master catalog 
U for user catalog 

A for non-VSAM data set 


The user work area that is based on CIRWA is shown in Figure 16-3. 


ines | rie emensorning 


AREALN Length of work area (an unsigned, 16-bit number). 
2 DATALIN Length of data returned +4 (an unsigned, 16-bit number). 


Variable DATA An array of entries where data is stored. Each entry consists of a 1-byte 
type field followed by a 44-byte name field. The array has an end 
indicator of X‘FF’. 


Figure 16-3. User Work Area for CIRPARM 


When you specify a data set name, a volume list is built in your work area. A 
volume list consists of an entry for each volume on which part of the data set 
resides; it is preceded by a 2-byte field that contains a count of the number of 
volumes in the list. The count field is followed by a variable number of 12-byte 
entries. Each 12-byte entry consists of a 4-byte device code, a 6-byte volume 
serial number, ans a 2-byte sequence number. As many as 20 of these 12-byte 
entries can be built in your work area. The volume list has an end indicator of 
X‘FF’. Figure 16-4 shows the format of the volume list. 
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J 


Cc 


Number 
of Bytes Contents or Meaning 


Reserved. 


Number of volumes on which part of the data set resides. 
DEVTYP Device type. 


VOLSER Volume serial number. 


FILESEQ File sequence number. (This field is provided for compatibility with the 
OS/VS catalog, and is used for non-VSAM data sets that reside on tape 
volumes.) 


Reserved. (Contains X‘FF’.) 


Figure 16-4. Volume Information Format 


Return Codes from IKJEHCIR 


The IKJEHCIR return codes have the following meaning: 


Return Code Meaning 


Hexadecimal 
00 Successful completion of the request. 
04 The LOCATE macro instruction has failed. The LOCATE return code will be stored 


in CIRLOCRC. 
0C Volumes were returned by LOCATE, indicating a dsname (fully qualified) was passed 


in the parameter list but options other than volumes were requested. The list of the 
volumes returned by LOCATE is in the work area. 


Return Codes from LOCATE 


The LOCATE return codes have the following meaning: 


Return Code Meaning 


Hexadecimal 
00 Successful completion of the request. 
04 The required catalog does not exist, it cannot be opened, or there is a closed chain of 


OS CVOL pointers. 
08 One of the following happened: 
@ The entry was not found. If in an OS CVOL, register 0 contains the number of 
valid index levels. If in an ICF or a VSAM catalog, register 0 contains the 


catalog return code. 


@® The user is not authorized to perform this operation. Register 0 contains 
hexadecimal 38. 


@ A generation data group (GDG) alias was found. Register 0 contains the number 
of valid index levels. The alias name was replaced by the true name. 


0C One of the following happened: 
@ An index or generation data group base entry was found when the list of qualified 


names was exhausted. Register 0 contains the number of valid index levels. The 
work area contains the first block of the specified index. 
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@® An alias entry was found. The alias name was replaced in the user parameter list 


by the true name. 
@® = An invalid low-level GDG name was found. 2 
10 A data set exists at other than the lowest index level specified. Register 0 contains the 


number of the index level where the data set was encountered. 
14 A syntax error exists in the name. 
18 One of the following happened: 


@® Permanent J/O error occurred. Register 0 contains the VSAM or JCF return 
code, or 0 if in an OS CVOL. 


@® WNonzero ESTAE return code. 
@® ~=Error in parameter list. 


IC The relative track address supplied to the LOCATE routine is outside of the 
SYSCTLG data set extents. 


20 Reserved. 
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Chapter 17. Default Service Routine IKJEHDEF) 


The default service routine (IKJEHDEF) constructs a fully-qualified data set 
name when the calling routine provides a partially-qualified data set name. A 
fully-qualified data set name has three fields: a userid, a data set name, and a 
descriptive qualifier. 


Use the CALL, CALLTSSR or LINK macro instruction to invoke the default 
service routine. 


IKJEHDEF may be invoked in either 24- or 31-bit addressing mode. However, 
all input passed to IKJEHDEF must reside below 16 Mb in virtual storage. 
IKJEHDEF executes in 24-bit addressing mode and returns control in the same 
addressing mode in which it is invoked. 


At entry, general register 1 must point to the default parameter list (DFPL). 
IKJEHDEF then invokes the catalog information routine (IKJEHCIR) to search 
the system catalog for the required qualifiers. When the search argument is 
satisfied, the default service routine returns to the calling control program. All of 
the general registers are restored except for register 15 which contains the return 
code. 


Note: For additional information concerning the default service routine, see 
Terminal Monitor Program and Service Routines Logic. 
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Chapter 18. Testing a Newly-Written TMP or CP -- The TEST 
Command 


The TEST command permits a user at a terminal to test an assembly language 
program, including a user written TMP, command processor, or application 
program. 


You test a program by issuing the TEST command and the various TEST 
subcommands that perform the following basic functions: 


@ Execute the program under test from its starting address or from any address 
within the program. 


@ Display selected areas of the program as it currently appears in virtual 
storage, or display the contents of any of the registers. 


e Interrupt the program under test at a specified location or locations. Once 
you have interrupted the program, you can display areas of the program or 
any of the registers, or you can issue other subcommands of TEST to be 
executed before returning control to the program being tested. 


@ Change the contents of specified program locations in virtual storage or the 
contents of specific registers. You do this with the TEST assignment 
function. 


In addition to these basic debugging functions, the TEST command processor 
provides other functions such as listing data extent blocks (DEBs), data control 
blocks (DCBs), task control blocks (TCBs), program status words (PSWs), and 
providing a virtual storage map of the program being tested. 


A complete list of the TEST subcommands and a short description of their 
functions is provided in Figure 18-1. 
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Subcommand Name 
ALLOCATE (XA only) 
AND (XA only) 
= (Assignment) 

AT 
ATTRIB (XA only) 


CALL 

CANCEL (XA only) 
COPY 

DELETE 

DROP 

END 

EQUATE 

EXEC (XA only) 
FREEMAIN 
GETMAIN 


GO 
HELP 


LINK (XA only) 
LIST 


LISTALC (XA only) 
LISTBC (XA only) 
LISTCAT (XA only) 


LISTDCB 


LISTDEB 


LISTDS (XA only) 
LISTMAP 
LISTPSW 


LISTTCB 


Function > 
Allocates data sets required by a program intended for execution. 

Performs the logical AND function on addresses. 

Assigns values to one or more locations. 


Establishes breakpoints at specified locations. 


Builds a list of attributes for non-VSAM data sets, which are to be 
dynamically allocated. 


Initiates execution of a program at a specified address. 
Halts processing of batch jobs submitted for the terminal. 
Moves data fields or addresses. 

Deletes a load module anywhere in virtual storage. 
Removes symbolic addresses from the symbol table. 
Terminates all functions of the TEST command. 

Adds a symbolic address to the symbol table. 

Executes a CLIST. 

Frees a specified number of bytes of virtual storage. 


Acquires a specified number of bytes of virtual storage for use by the 
program being processed. 


Restarts a program at the point of interruption or at a specified address. 


Lists the TEST subcommands and explains their functions, syntax, and 
operands. ) 


Invokes the linkage editor service program. 


Displays the contents of specified areas of virtual storage or the contents of 
specified registers. 


Displays a list of data set names allocated during the current TSO session. 
Displays a listing of the contents of the SYS1.BRODCAST data set. 


Lists catalog entries by name or entry type and lists selected fields for each 
entry. 


Lists the contents of a data control block (DCB). You must specify the 
address of the DCB. 


Lists the contents of a data extent block (DEB). You must specify the 
address of the DEB. 


Displays attributes of specific data sets at the terminal. 
Displays a storage map of any virtual storage assigned to a program. 


Displays the program status word (PSW). You can specify the address of 
any PSW. 


Lists the contents of the task control block (TCB). You can specify the 
address of any TCB. 


Figure 18-1 (Part 1 of 2). 
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The TEST Subcommands 


Cc 


When You Would Use 


Subcommand Name 
LOAD 

OFF 

OR (XA only) 
PROFILE (XA only) 
PROTECT (XA only) 
QUALIFY 


RENAME (XA only) 


RUN 

SEND (XA only) 
STATUS (XA only) 
SUBMIT (XA only) 
TERMINAL (XA only) 
UNALLOC (XA only) 


WHERE 


Figure 18-1 (Part 2 of 2). 


TEST 


Function 

Loads a program into virtual storage for execution. 
Removes breakpoints. 

Performs the logical OR function on addresses. 
Establishes, changes, or lists the user profile. 

Prevents unauthorized access to a non-VSAM data set. 


Establishes the starting or base location for symbolic or relative addresses; 
resolves external symbols within load modules. 


Changes the name of a non-VSAM cataloged data set or a member of a 
PDS or creates an alias for a member of a PDS. 


Voids all breakpoints so that a program can execute to termination. 
Sends a message to another terminal user or to the system operator. 
Displays the status of batch jobs for processing. 

Submits one or more batch jobs for processing. 

Defines the operating characteristics of your terminal. 


Frees data sets under TSO TEST. Because FREE is an alias for the 
FREEMAIN subcommand, you must UNALLOC to free files under TEST. 


Displays the absolute address of a symbol or entry point, and its relative 
location within the CSECT. 


The TEST Subcommands 


There are two basic situations in which you might want to use the TEST 


command: 


1. You want to test a program currently active in the system. 
2. You want to test a program not currently being executed. 


Testing a Currently Executing Program 


You may want to TEST a currently executing program either because it has 
begun to abnormally terminate, or because you want to check through the current 
environment to see that the program 1s executing properly. 


e Ifa program has begun to abnormally terminate, you receive a diagnostic 
message from the terminal monitor program (TMP) and then a READY 
message. The TMP is in effect asking, “Do you want to terminate your 
program or test it?” If you respond with anything but TEST, your program 
is abnormally terminated by the ABEND routine. If, however, you issue the 
TEST command (no program name should be supplied), the TEST command 
processor is given control, and you can use the TEST subcommands to debug 
the defective program. 


e If you just want to look at the current environment of an executing program 
that is not terminating abnormally, enter an attention. The currently active 
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program is not detached and the TMP responds to your interruption by 
issuing its usual READY message. Issue the TEST command (no program 
name) and the currently active program remains in storage under the contro] 
of the TEST command processor. You can then use the TEST subcommands 
to investigate the current storage situation. 


Note that in the case of both the ABEND or the attention interruption, you 
do not enter a program name following the TEST command. If you enter the 
TEST command followed by the name of the currently active program, you 
lose the current in-storage copy of the program and TEST loads a new copy. 


Testing a Program Not Currently Executing 


The second use of the TEST command processor, testing a program not currently 
being executed, requires that you enter a program name along with the TEST 
command. When the terminal monitor program issues a READY message to 
request a command, enter the command: 


TEST program name 


(There are other optional operands of the TEST command but they are not 
necessary for this example.) The TEST command processor is given control and 
it loads a copy of the named program. The program can be a newly written 
TMP, CP, or application program. 


Programs to be tested in this manner must be link edited members of partitioned 
data sets, or object modules in sequential or partitioned data sets, loadable by the 
Loader. 


While the program is under the control of TEST, you can step through the 
program using breakpoints, investigate or alter the environment at any time, 
change instructions or register contents, force entry into various subroutines, and 
perform other debugging operations online and immediately. 


It 1s this second use of the TEST command processor, especially the debugging of 
newly written code, that this section discusses. For an additional discussion of the 
TEST command and its operands, see TSO/E Command Language Reference. 


Addressing Restrictions 


The TEST command processor can resolve internal and external symbolic 
addresses only if these addresses are available and can be obtained by TEST. 
Within certain limitations, symbolic addresses are available for both object 
modules (processed by the Loader) and load modules (fetched by contents 
supervision). To ensure availability of symbols, use the EQUATE subcommand 
of TEST to define the symbols you intend to use. 


External symbols, such as CSECT names, can be available for both object 
modules and load modules. Object modules require that the Loader had enough 
storage to build in-storage composite external symbol dictionary (CESD) entries. 
Load modules must have been fetch2d into virtual storage by the tested program 
or by the LOAD subcommand of TEST. 
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Internal symbols are available only for load modules. You can refer to most 
internal symbols in load modules if you specified the TEST parameter during 
both assembly and linkage editing. Certain internal symbols, however, are not 
available. These include the names on EQU, DSECT, LTORG, and ORG 
assembler statements, and the symbolic names contained in system routines that 
operate in zero protection key. 


Provided a module invoked by the tested program is not fetched from the link 
pack area, CSECT names within the module can be accessed. If this module is 
also assembled and link-edited with the TEST parameter, symbolic addresses can 
also be accessed. 


If the necessary conditions for symbol processing are not met, you can use 
absolute, relative, or register addressing, but you cannot refer to symbols, unless 
you have previously defined them with the EQUATE subcommand of TEST. 


Executing a Program under the Control of TEST 


Any program, if it is a link-edited member of a partitioned data set or an object 
module in a sequential or partitioned data set, can be executed under the control 
of the TEST command processor. 


Issue the TEST command followed by the program name and those operands of 
the TEST command that either define the program or are necessary to its 
operation. These operands may consist of: parameters necessary to the operation 
of the program under TEST, the keyword LOAD or OBJECT depending on 
whether the program is a load or an object module, and the keyword CP or 
NOCP, depending upon whether the program to be tested is a command 
processor or not. 


Any parameters that you specify in the TEST command are passed to the named 
program as a standard operating system parameter list; that is, when the program 
under TEST receives control, register one contains a pointer to a list of addresses 
that point to the parameters. 


If the program to be tested is a command processor, include the keyword CP (the 
default is NOCP). The test routine creates a command processor parameter list 


(CPPL), and places its address into register 1 before loading the program. 


Figure 18-2 shows the sequence of operations leading up to and following the 
issuance of the TEST command. 
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MYPROG 


Figure 18-2. Issuing the TEST Command 


In Figure 18-2, the following sequence of operations takes place: 


hs 


The terminal monitor program issues a READY message to the terminal to 
indicate that the user should enter a command. 


The user at the terminal answers with the command: 


TEST (MYPROG) CP 


The TMP uses the command scan service routine to determine that a valid 
command has been entered, and invokes TEST via a SYNCH macro. 


The TEST command processor, using the parse service routine, determines 
that the user wants a command processor parameter list built and passed to 
the load module (LOAD is the default) MYPROG. TEST builds the CPPL, 
in storage below 16 Mb in virtual storage, places its address into register one, 
and attaches the TEST loader which transfers control to MYPROG using the 
XCTL macro. XCTL loads and passes control to the tested program based 
on the program’s AMODE and RMODE attributes. 


The TEST command processor informs the user at the terminal that it is 
ready to accept subcommands. TEST does this by writing the message TEST 
at the terminal. 
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From this point on, the user can use any of the facilities provided by the TEST 
( subcommands to test his program. 


Establishing and Removing Breakpoints within a Program 


Use the AT subcommand to establish breakpoints within the program being 
tested. Then issue the GO subcommand to begin execution of the program. To 
begin executing a newly loaded program, enter the subcommand GO - no address 
is required. When the breakpoints are encountered as the program is being 
executed, processing is temporarily halted, and the message AT address is written 
to the terminal. You can then examine the executing program, its registers, and 
data areas to see that it has been executing properly. 


There are two methods of accomplishing this: 


1. You can specify a list of subcommands on the AT subcommand when you 
establish a breakpoint. When a breakpoint is encountered, the TEST 
command processor issues each of the specified subcommands as if it had 
been entered from the terminal at that time. The subcommands execute and 
display the results of their execution at the terminal. If you specify GO as the 
last subcommand, control is automatically returned to the program under 
TEST at the point of interruption. If you do not specify GO as the last 
subcommand in the list, control is returned to you at the terminal after the 
last subcommand is executed. If you determine from the information 
displayed by the subcommands that your program has executed properly up 
to that breakpoint, issue the GO subcommand. Your program resumes 
execution at the point of interruption and continues execution until another 

| breakpoint, or the end of the program, is reached. 


2. If you do not specify a list of subcommands when you issue the AT 
subcommand, the TEST command processor returns control to you at the 
terminal each time a breakpoint is encountered. You can then check on your 
program’s execution by entering the TEST subcommands directly from the 
terminal. 


Issue the OFF subcommand with no address operand to remove all breakpoints 
previously established. Issue the OFF subcommand followed by an address, a list 
of addresses, or a range of addresses to remove a single breakpoint, several 
breakpoints, or all breakpoints occurring within the range of addresses. 


Displaying Selected Areas of Storage 


Use the various LIST subcommands to display the contents of a specified area of 
storage, registers, or various control blocks at your terminal, or to write this 
information to a data set. There are six variations of the LIST subcommand that 
display selected areas of storage: 


1. LIST 

2. LISTMAP 

3. LISTTCB 

4. LISTDEB 
Cc 5. LISTDCB 

6. LISTPSW 
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LIST: Use the LIST subcommand to display areas of storage or the contents of 
registers. The address required as an operand of the LIST subcommand can be 
one address, a list of addresses, or a range of addresses. The address may be 
specified as a symbolic address if a symbol table exists and contains the requested 
symbolic address. If no symbol table exists (the program was not link-edited or 
did not save a symbol table), you can use the EQUATE subcommand to create a 
symbolic address for any location within the program, or you can specify the 
address as a relative address, an absolute address, or as a register containing an 
address. 


If you use the LIST subcommand to list information found at an address specified 
by a symbol contained in a symbol table, the information 1s displayed 1n the 
character type and the length specified in the symbol table. You can, however, 
override the attributes contained in the symbol table by including attribute 
operands on the LIST subcommand. 


Use the LIST subcommand at any point during the execution of your program 
(use AT or an attention interruption to stop the execution of the program) to 
determine whether data areas and registers contain proper data. If the data 
displayed is not what it should be, use the TEST subcommands to determine why 
the data is not as expected, or to modify the data in virtual storage and continue 
execution of the program. 


LISTMAP: Use the LISTMAP subcommand to display at your terminal a map 
of all virtual storage assigned to the program being tested. Some of the 
information displayed after issuance of the LISTMAP subcommand 1s: 


@ Region size 
e Task Control Block address 
e Program name, length, and location in virtual storage 


e Active request blocks, RB types, and the names of the programs associated 
with each of the RBs 


LISTTCB: Use the LISTTCB subcommand to display the entire task control 
block of the program being tested, or any fields of that TCB. The information 
displayed is formatted, and each field is identified according to the field names 
contained in Data Areas. 


If you want to display the TCB for the program being tested, enter the LISTTCB 
subcommand with no address. If you want to display another TCB on the TCB 
queue, you must include the address of the TCB as an operand of the LISTTCB 
subcommand. 


LISTDEB: Use the LISTDEB subcommand to display the basic section and any 
direct access sections of any valid data extent block (DEB), or any fields of that 
DEB. The information displayed is formatted according to the field names of 
the data extent block as contained in Data Areas. 
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Changing Instructions, 


The LISTDEB subcommand requires the address of a DEB as an operand. 


LISTDCB: Use the LISTDCB subcommand to display the contents of a data 
control block (DCB). The information displayed is formatted, and each field is 
identified according to the field names contained in the publication Data Areas. 


The LISTDCB subcommand requires the address of a DCB as an operand. If 
you have created the DCB within the program being tested, use the address of the 
DCB macro instruction used to create the DCB. You can also obtain the address 
of the DCB from the DEBDCBAD field of the DEB displayed with the 
LISTDEB subcommand. 


LISTPSW: Use the LISTPSW subcommand to display the current program 
status word or any of the PSWs at your terminal. The PSW is displayed, 
formatted by field. If you issue the LISTPSW subcommand with no address 
following the subcommand, the current PSW is displayed at your terminal. If 
you want to display any of the other PSWs at your terminal, supply the address 
of the PSW you want to see as an operand of the LISTPSW subcommand. A list 
of the permanent virtual storage locations of all PSWs can be found in Principles 
of Operation. 


Data Areas, or Register Contents 


Once you have listed those areas of virtual storage that help you determine just 
what has occurred in your program, you can use the assignment function of the 
TEST command to make corrections within the virtual storage copy of the code, 
or to change the contents of data areas or registers. 


Enter the address at which you want the new data entered, a code indicating the 
data type, and the new data you want entered at that address. The address must 
conform to the address restrictions already discussed. The new data must be 
contained within single quotes. The data type codes can be found in TSO/E 
Command Language Reference. 


One problem that can arise during a debugging session occurs when you want to 
replace a section of the program under TEST but the replacement code is longer 
than the section to be replaced. If you type in the beginning address of the 
section to be replaced, followed by a portion of code longer than the segment to 
be replaced, you will overlay some functional code. You can solve this problem 
with the GETMAIN subcommand of TEST. 


Issue the GETMAIN subcommand of TEST to obtain a work area in which to 
build your replacement segment of code. The GETMAIN subcommand displays 
the address of the beginning of the virtual storage area it obtained for you. The 
LOC operand enables you to specify where you want the storage to be obtained 
in terms of below or above 16 Mb in virtual storage. Use the assignment 
subcommand of the TEST command to place a branch to the new area at the 
beginning address of the code you want to replace in your module. Use the 
assignment or COPY subcommand to build your code segment in the newly 
obtained area. As the last instruction in your newly written code, place a branch 
back to the point within your module at which you want processing to resume. 
You can then use the GO subcommand to restart your program at some point 
before the branch. Your program will execute through the branch instruction and 
into the newly written code. If the new code works, you will execute the new 
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instructions and branch back into your original code. Later, you can use the 
LIST subcommand to display the newly written code in a form useful to you, 
enter it into your program, and reassemble your now executable module. 


Forcing Execution of Program Subroutines 


Certain paths through some programs are difficult to test because the 
combination of events leading to that path is difficult to produce. 


One example of this problem is processing after return codes. Your module might 
respond differently according to the codes returned to it by some other module or 
some other, not yet written, section of code. You can use the AT subcommand to 
insert a breakpoint in your program at the point where it passes control to the 
unavailable code; the assignment function of TEST to set register 15 to the 
desired return code; and the GO subcommand to begin execution of your 
program at the point where control would have been returned. Using this 
sequence of TEST subcommands, you can test your module’s response to each 
possible return code. 


Using TEST after a Program ABEND 


If a program running under TSO begins to ABEND, a diagnostic message 
containing the ABEND code is written to the terminal, ABEND processing is 
halted, and control is returned to either the TMP or TEST. If the program was 
running under the control of the TEST command processor, control is returned to 
TEST and you can immediately begin to use the TEST subcomma'nds to 
determine the cause of the error. If the program was not running under TEST, 
control is returned to the terminal monitor program. You can then enter the 
TEST command (no program name should be entered) to place the abnormally 
terminating program under control of the TEST command processor. 


Use the ABEND code to determine the type of interruption that occurred. Issue 
the WHERE subcommand to determine where the interruption occurred. 


The WHERE subcommand is especially helpful. If you enter the WHERE 
subcommand without an address, TEST displays the address of the next 
executable instruction, the related load module and CSECT names, and the 
hexadecimal offset of the displayed address. 


The instruction address, and the information returned by the WHERE 
subcommand pinpoint the error. 


Use the LIST subcommand to display the instructions leading up to the error 


condition, and to display data areas and registers used in those instructions. This 
information should be sufficient to determine the cause of the error. 
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Determining Data Set Information 


( If you want to investigate the condition of any of your data sets, perform the 
following operations: 


1. Use the LISTTCB subcommand to display the TCB for the terminating task. 


2. Use the contents of the TCBDEB field as an operand of the LISTDEB 
subcommand to gain access to the data extent block queue. 


3. Use the contents of the DEBDCBAD field in each of the DEBs in the DEB 
queue, or the addresses of any DCB macro instructions coded within your 
program, as an operand of the LISTDCB macro instruction to list the data 
control blocks. 


These control blocks contain the addresses of other control blocks useful in the 
debugging process. See Data Areas. 
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Appendix A. Notation for Defining Macro Instructions 


The notation used in this publication is described in the following paragraphs. 


1. The set of symbols listed below are used to define macro instructions, but 
should never be written in the actual macro instruction: 


hyphen - 
underscore _ braces { } 
brackets [] 

ellipsis 


The special uses of these symbols are explained in paragraphs 4-8. 


2. Uppercase letters and words, numbers, and the set of symbols listed below 
should be written in macro instructions exactly as shown in the definition: 
apostrophe ’ 
asterisk + 
comma ; 
equal sign = 
parentheses ( ) 
period 


3. Lowercase letters, words, and symbols appearing in a macro instruction 
definition represent variables for which specific information should be 
substituted in the actual macro instruction. 


Example: If name appears in a macro instruction definition, a specific value 
(for example, ALPHA) should be substituted for the variable in the actual 
macro instruction. 


4. Braces group related items, such as alternatives. 


Example: The representation 


A 
B 
Cc 


ALPHA= ( 72) 


indicates that a choice should be made among the items enclosed within the 
braces. If A is selected, the result is ALPHA=(A,D). If B is selected, the 
result can be either ALPHA=(,D) or ALPHA =(B,D). 


5. Brackets also group related items; however, everything within the brackets is 
optional and may be omitted. 
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Example: The representation 
>) 2 


indicates that a choice can be made among the items enclosed within the 
brackets or that the items within the brackets can be omitted. If B is selected, 
the result is: ALPHA=(B,D). If no choice is made, the result is: 

ALPHA =(,D). 


A 
ALPHA=(| B 
S 


6. Hyphens join lowercase letters, words, and symbols to form a single variable. 
Example: If member-name appears in a macro instruction definition, a 
specific value (for example, BETA) should be substituted for the variable in 


the actual macro instruction. 


7. An underscore indicates a default option. If an underscored alternative is 
selected, it need not be written in the actual macro instruction. 


Example: The representation 


A A 
B or {8B 
C Cc 


indicates that either A or B or C should be selected; however, if B is selected, 
it need not be written because it is the default option. 


8. An ellipsis indicates that the preceding item or group of items can be repeated 2 
more than once in succession. 


Example: The representation 


ALPHA[,BETA]... 


indicates that ALPHA can appear alone or can be followed by ,BETA any 
number of times in succession. 


Note: To designate register 0 and register 1 on a macro invocation, use (0) and 
(1), respectively. You cannot use a symbolic variable to designate these registers. 


A-2  TSO/E Guide to Writing a TMP or a CP 


Appendix B. Using VTAM Full-Screen Mode 


This appendix outlines the steps for writing a full-screen command processor, 
describes the full-screen protection responsibilities that you must consider when 
writing an attention exit routine, and contains several examples illustrating the 
processing that occurs when running a full-screen command processor. You need 
to use the following macros when writing a full-screen command processor: 


STFSMODE Set full-screen mode. 

STLINENO Set the line number. 

STTMPMD Set terminal display manager options. 
TGET Get a line from the terminal. 

TPUT Write a line to the terminal. 


Earlier sections of this book contain the complete syntax of each of these macros; 
this appendix discusses only the pertinent keywords. 


Writing a Full-Screen Command Processor 


Follow these steps when writing a full-screen command processor: 
1. Set full-screen mode on. 


2. If replacing a display terminal manager, such as Session Manager, put the 
command processor in control. 


3. Write to and get information from the terminal as necessary. 
4. Exit and reenter full-screen mode as necessary. 


5. Terminate the full-screen command processor and, if it replaced a display 
terminal manager, return control to the display terminal manager. 


Each of these steps is described in more detail on the following pages. Figure B-1! 
shows the macros used when writing a full-screen command processor. 
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STFSMODE ON, INITIAL= YES _ Set full-screen mode on 

STTMPMD ON Give control to the command processor 
TPUT FULLSCR Issue a full-screen message 

TGET ASIS Get input from the terminal 


STLINENO LINE=] Clear the screen and exit 
full-screen mode expecting 
to reenter it later 


TPUT EDIT Issue a non-full screen message 


STFSMODE ON Reenter full-screen mode 

TPUT FULLSCR Issue a full-screen message 

TGET ASIS Obtain RESHOW request 

TPUT FULLSCR Reissue the previous full-screen message 
TGET ASIS Get input from the terminal 


STLINENO LINE=1 Clear the screen 

STFSMODE OFF Exit full-screen mode and set defaults 

STTMPMD OFF Return control to the display 
termina] manager 

TPUT EDIT Display session summary information 


Figure B-1. Macros Used to Write a Full-Screen Command Processor 


(1) Set Full-Screen Mode On 


Use the STFSMODE macro to set full screen mode on. This macro prevents 
unexpected non-full-screen messages from overlaying the screen. For example, 
unexpected messages from the operator or from other TSO users could cause 
invalid input to be sent to the command processor. Also, STFSMODE prevents 
full-screen messages from overlaying unexpected non-full-screen messages before 
the user has a chance to read them. 


To prevent unnecessary protection of the screen contents, specify INITIAL = YES 
when you use the STFSMODE macro. If you specify INITIAL= YES and the 
first message is a full-screen message, TSO/VTAM does not display three asterisks 
at the terminal (which would require the user to press the ENTER key). 
TSO/VTAM sets the INITIAL keyword indicator to NO after the command 
processor sends the first full screen of information. For subsequent full screens of 
output that follow non-full screens of output, TSO/VTAM displays the three 
asterisks at the terminal before processing the full-screen output. See “Examples 
of Full-Screen Command Processor Operation” at the end of this Appendix for a 
description of the processing that takes place when INITIAL= YES and 
INITIAL=NO. 
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TERMINAL BREAK Support for Full-Screen Mode: When a command 
processor establishes full-screen mode, VTAM treats all devices as if the terminal 
user had entered the TERMINAL NOBREAK command. If the user specifies 
TERMINAL BREAK before a full-screen command processor is invoked, VTAM 
supports the BREAK mode before the command processor enters full-screen 
mode and whenever the command processor exits from full-screen mode. See 
TSO Extensions Command Language Reference for a description of the 
TERMINAL command. 


(2) Give Control to the Command Processor 


If your command processor replaces a display terminal manager, such as Session 
Manager, use the STTMPMD macro to put the command processor in control. 
If you do not use this macro, the display terminal manager traps line-mode 
messages so the user does not see them in the ordinary way. If your command 
processor does not replace a display terminal manager, you do not need this 
macro. 


(3) Write to and Get Information from the Terminal 


Use the TPUT and TGET macros to provide interaction between the user and the 
command processor. TPUT FULLSCR, TPUT NOEDIT, and TPG transmit a 
full-screen of output to the terminal. 


Unlocking the Keyboard: When a command processor issues a TGET following a 
TPUT FULLSCR, VTAM unlocks the display keyboard. When a command 
processor issues a TGET following a TPUT NOEDIT or a TPG, VTAM does not 
unlock the keyboard. Users of TPUT NOEDIT and TPG are responsible for all 
device command and write-control-character bit settings. 


Receiving Data: TGET ASIS reads a full screen of input containing the user’s 
reply from the terminal. You can also use the NOEDIT keyword on the 
STFSMODE macro along with the TGET macro to get a full-screen message 
from the terminal. 


NOEDIT Mode: To obtain a full screen of input (via a TGET macro) that is not 
edited in any way, the command processor can specify the NOEDIT keyword on 
STFSMODE. Regardless of the options the command processor specifies on the 
TGET macro, in NOEDIT mode, VTAM does not edit the data, break it into 
separate input lines, or modify it. WTAM receives the input from the terminal 
and puts it on the input queue intact. To establish NOEDIT mode, the command 
processor must issue: 


STFSMODE ON,NOEDIT=YES 


Use of the NOEDIT keyword has no effect on the treatment of TPUTs and 
TPGs. 


Considerations for Invoking an External Function: Before a terminal monitor 
program or command processor calls an external function or system service, it 
must check that the fullscreen mode and input mode (normal or NOEDIT) are 
acceptable to the function or service. For example, if the NOEDIT input mode is 
in effect when control passes to an external routine, and the invoked routine does 
not change the input mode, TGET returns data in an unedited format. 
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Protection of Screen Contents: When non-full-screen messages are issued in 
full-screen mode, TSO/VTAM clears the screen and sends the non-full-screen 
messages to the screen. When the next full-screen message 1s issued, TSO/VTAM 
protects the screen contents in order to allow the user time to read the 
non-full-screen messages. TSO/VTAM protects the screen by displaying three 
asterisks (***) after the last non-full-screen message and unlocking the keyboard. 
When finished reading the screen, the user presses ENTER to allow full-screen 
processing to resume. 


Restoration of Screen Contents: As part of the screen protection function, 
TSO/VTAM discards the full-screen message that immediately follows 
non-full-screen messages, unless issued with the HOLD option of the TPUT 
macro. To receive the RESHOW code, the full-screen command processor must 
issue a TGET macro after every TPUT FULLSCR macro. 


The RESHOW indicator tells the command processor to completely restore the 
screen contents. That is, the command processor must reissue the previous 
full-screen message. See “Examples of Full-Screen Command Processor 
Operation” at the end of this Appendix for an example of RESHOW processing. 


RESHOW requests can come from VTAM and from users. Users can request a 
restoration of the screen by pressing the RESHOW key. The VTAM default 
RESHOW code is X‘6E’, which represents the PA2 key. If the command 
processor uses a PF key for the RESHOW key, it must specify the RSHWKEY 
keyword on the STFSMODE macro when it first turns on full-screen mode. To 
set the RESHOW key, issue: 


STFSMODE ON,RSHWKEY=n 


where nis the PF key number. VTAM uses the hexadecimal representation of the 
specified PF key as the RESHOW code. 


(4) Exiting and Reentering Full-Screen Mode 


If the command processor issues non-full-screen messages (or invokes routines 
that issue non-full-screen messages), it can issue the STLINENO macro to set 
full-screen mode off and to set the line number for the next non-full-screen 
message. In so doing, the command processor eliminates the screen protection 
function and determines where the next non-full-screen message appears. If the 
line number is set to 1, VTAM clears the screen. When the command processor 
issues the last non-full-screen message (or when the invoked routine returns 
control to the command processor), the command processor must issue 
STFSMODE ON to reestablish full-screen mode. The command processor must 
issue the STFSMODE macro before it issues the next full-screen message macro. 


If the command processor exits full-screen mode, expecting to reenter full-screen 
mode at a later time before termination, the command processor must use 
STLINENO to set full-screen mode off. (Use of STFSMODE to set the mode off 
results in the RESHOW key being set to the default.) After a TGET request, the 
command processor can issue: 


STLINENO LINE=n 
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where n is the desired line number. It does not have to specify MODE=OFF on 
the STLINENO macro because that is the default for the MODE keyword. 


When all non-full-screen messages are completed, issue STFSMODE ON before 
issuing the next full-screen message macro. When the command processor returns 
to full-screen mode, it must issue the TGET macro to read the RESHOW request 
in the input queue. It can then continue to transmit and receive information from 
the terminal. 


You may want either to clear part of the screen before issuing STLINENO, or to 
display information that is to remain on the screen after the STLINENO macro is 
issued. In either case, issue a full-screen TPUT or TPG macro (including the 
HOLD option) before issuing the STLINENO. The HOLD option specifies that 
the program that issued the TPG macro cannot continue its processing until the 
output line is written to the terminal or deleted. Therefore, the full-screen 
message reaches the terminal before the STLINENO macro takes effect. 


Clearing the Terminal Screen: Because VTAM clears the screen when the line 
number is set to 1, STLINENO LINE $1 is an efficient way for the command 
processor to clear the screen. Use of a full-screen TPUT or TPG macro 
(including the HOLD option) to clear the screen reduces performance because it 
causes a swap-out of the address space to wait for the I/O to complete. 


(5) Full-Screen Command Processor Termination 


When a TGET is satisfied with data that causes the command processor to begin 
exit processing, the following termination procedure is recommended: 


STLINENO LINE =1 Causes VTAM to clear the screen. 

STFSMODE OFF Exits full-screen mode and resets the RESHOW key and NOEDIT mode 
to the defaults. 

STTMPMD OFF Returns control to a display terminal manager, such as Session Manager. 

non-full-screen TPUTs Optional macros that provide session summary information or other types 


of termination information. 


If the command processor issues a TPUT or TPG macro before (or instead of) 
issuing the STLINENO macro, it must use the HOLD option to guarantee that 
the message reaches the terminal before VTAM sets full-screen mode off. If the 
macro is handling a full-screen message, the command processor must issue a 
TCLEARQ INPUT macro just before termination to clear the RESHOW code 
that VTAM put on the input queue for screen protection. 


Full-Screen Protection Responsibilities of Attention Exit Routines 


To maintain screen protection when the user presses the PA] or ATTENTION 
key, the command processor must have an attention exit routine. When the 
terminal user presses the PAI or ATTENTION key, VTAM sets FULLSCR to 
OFF, the RESHOW key to the default, and NOEDIT mode to NO. if the 
command processor does not have an attention exit and the user presses ENTER 
(in response to the attention indication), the command processor resumes 
execution at the point of interruption with these default values. If the command 
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processor has an attention exit routine, the exit routine must issue the 
STFSMODE macro to reestablish full-screen mode, the desired RESHOW key, 
and NOEDIT mode. In this way, the attention exit routine maintains screen 
protection. 


Examples of Full-Screen Command Processor Operation 


The following examples show these functions: 


RESHOW in full-screen message processing 


INITIAL = YES on the STFSMODE macro when the first message is a 
full-screen message 


INITIAL= YES on the STFSMODE macro when the first message is a 
non-full-screen message 


INITIAL=NO on the STFSMODE macro. 


Each example consists of a chart followed by an explanation. The heading for 
each chart list the three components involved in the processing: the command 
processor, TSO/VTAM, and the terminal. The items listed under each component 
relate to that component. The numbers in the left-hand column of the charts 
refer to the events described in the explanation. The arrows in the chart indicate 
the flow of the processing. 
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Function of RESHOW in Full-Screen Message Processing 


( Figure B-2 shows the use of RESHOW when a command processor, operating in 
full-screen mode, issues a full-screen message while non-full-screen messages are 
being displayed at the terminal. 


[coma Pener —[ SOTA 


input ENTER 
non- i See -screen message | non-full-screen message | 


i non-full-screen message n non-full-screen message n 


. | TPUT 
full-screen message | ei, +08 
TGET 
RESHOW ENTER 
full-screen message | <]——_________T full-screen message | 


(6) TGET a 


Figure B-2. Function of RESHOW in Full-Screen Message Processing 


The following events occur in Figure B-2: 


1. When the user presses the ENTER key to send input to the command 
processor, TSO/VTAM: 


@ Clears the screen. 
¢ @ Sounds the alarm (if the terminal has an alarm). 


e Displays non-full-screen messages. The operator or some other user 
could have sent these messages. 


2. As long as TSO/VTAM receives non-full-screen messages, it displays them, 
one after another on the screen. 


3. The command processor’s normal processing of input (see step 1) may cause 
it to send a full-screen message using the TPUT macro. When TSO/VTAM 
receives the full-screen message, it: 


e Displays three asterisks (***) at the terminal. 


e Unlocks the keyboard to ensure that the user has time to view the 
non-full-screen messages. 


e Discards the full-screen message that the command processor sent. 


4. After each full-screen message, the command processor issues a TGET macro. 
When the user presses the ENTER key to acknowledge having seen the 
non-full-screen messages, TSO/VTAM puts a RESHOW request on the input 
queue to tell the command processor to completely restore the screen 
contents. The command processor’s current TGET picks up this RESHOW 
request. 


5. The command processor responds to the RESHOW request by issuing a 
full-screen TPUT to restore the screen contents. TSO/VTAM displays the 
message at the terminal. 


( 6. The command processor issues a TGET macro. 
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Function of INITIAL= YES when the First Message is Full Screen 


Figure B-3 shows a situation in which the command processor specifies ») 
INITIAL = YES on the STFSMODE macro and issues a full-screen message as 
the first message. 


[Command Processor | TSO/VTAM 
READY READY 
a lb command name 
2. | STFSMODE 
INITIAL= YES 
full-screen message | C—O full-screen message | 


a 


Figure B-3. Function of INITIAL= YES when First Message is Full-Screen 


The following events occur in Figure B-3: 


1. TSO/VTAM displays the READY message at the terminal. In response to 
the READY message, the user enters a command name, such as ISPF. The 
command processor receives the command name. 


2. The command processor issues the STFSMODE macro with INITIAL= YES. 
3. The command processor sends a full-screen message to the terminal. 
TSO/VTAM sends the message without warning because the command 
processor specified INITIAL= YES and because its previous interaction with ) 


the terminal involved input, not output. There is nothing to protect. 


4. The command processor issues a TGET macro. 
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Function of INITIAL= YES when the First Message is Non-Full Screen 


If the command processor specifies INITIAL= YES on the STFSMODE macro, 
and the first message is a non-full-screen message, VTAM ignores the keyword 
and protects the screen contents. Figure B-4 shows this situation. 


[Command Processor | TSO/VTAM 
READY pe READY 
ee —— command name 
2. | STFSMODE 
INITIAL= YES 
oh -- non-full-screen message 1 non-full-screen message | 
TPUT 
full-screen message | 
5. | TGET 
RESHOW ENTER 


full-screen message | = full-screen message | 


a 


Figure B-4. Function of INITIAL= YES when First Message is Non-Full-Screen 


The following events occur in Figure B-4: 


|. TSO/VTAM displays the READY message at the terminal. In response to 
the READY message, the user enters a command name. The command 
processor receives the command name. 


2. The command processor issues the STFSMODE macro with INITIAL= YES. 


3. TSO/VTAM displays a non-full screen message. This could be a warning 
from the operator or a message from another user. 


4. The command processor sends a full-screen message to the terminal. 
TSO/VTAM protects the screen contents by sending three asterisks to the 
terminal and discarding the full-screen message. 


5. After each full-screen message, the command processor issues a TGET macro. 
When the user presses the ENTER key to acknowledge having seen the 
non-full screen message, TSO/VTAM puts a RESHOW request on the input 
queue to tell the command processor to completely restore the screen 
contents. The command processor’s current TGET picks up the RESHOW 
request. 


6. The command processor responds to the RESHOW request by issuing a 
full-screen message to restore the screen contents. TSO/VTAM displays the 


full-screen message at the terminal. 


7. The command processor issues a TGET macro. 
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Function of INITIAL=NO 


If the command processor specifies INITIAL = NO or INITIAL =NO is the J 
default, TSO/VTAM protects the screen before displaying the first full-screen 
message. Figure B-5 shows an example of this situation. 


[| Command Processor | __TS0/VTAM 
READY pe READY 
Se command name 
2. | STFSMODE 
INITIAL = NO 
3. | TPUT 
full-screen message | 
TGET 
—— ENTER 
TPUT 
full-screen message 1 full-screen message | 


(6. | 1GET =a ame 


Figure B-5. Function of INITIAL=NO 


The following events occur in Figure B-S: 


1. TSO/VTAM sends a READY message to the terminal. In response to the 
READY message, the user enters a command name. The command processor 
receives the command name. 


2. The command processor issues the STFSMODE macro with INITIAL=NO. 


3. The command processor sends a full-screen message to the terminal. J 
TSO/VTAM protects the screen contents by sending three asterisks to the 
screen and discarding the full-screen message that the command processor 
sent. 


4. After each full-screen message, the command processor issues a TGET macro. 
When the user presses the ENTER key, TSO/VTAM puts a RESHOW 
request on the input queue to tell the command processor to completely 
restore the screen contents. The command processor’s current TGET picks 
up the RESHOW request. 


5. The command processor responds to the RESHOW request by issuing a 
full-screen message to restore the screen contents. TSO/VTAM displays the 


full-screen message at the terminal. 


6. The command processor issues a TGET macro. 
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IKJSUBF 15-57 
IKJTERM = 15-39 
releasing storage allocated by parse 15-58 
parameter control list (PCL) 15-30 
example 15-98 
parameter descriptor entries (PDE) 15-30, 15-60 
combining list and range options 15-79 
description 15-60 
keyword parameters 15-83 
list option 15-76 
positional parameters 15-61 
range option 15-78 
parameter descriptor list (PDL) 15-60 
beginning the 15-30 
parameter formats 
TGET/TPUT/TPG 13-13 
parameter list 
attention exit parameter list (AEPL) 2-11 
catalog information routine parameter list 
(CIRPARM) | 16-1 
command processor parameter list (CPPL) 7-2 
command scan parameter list (CSPL) 15-5 
DAIR parameter list (DAPL) 10-4 
expansion 
execute form of TPUT 13-16 
list form of GTTERM § 14-4 
list form of TPG 13-16 
list form of TPUT 13-15 
standard and execute forms of TPUT 13-15 
standard, list, execute forms of TGET 13-17 
format for IKJEFFO02 
extended 8-5 
MTFORMAT=NEW 8-6 
MTFORMAT=OLD 8-6 
standard 8-4 
input/output parameter list (IOPL) 12-2 
parameter description list (PDL) 15-60 
parse parameter list (PPL) 15-59 
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structure required by command scan _ 15-5 
parameter string 

inserting keywords into 
parameter syntax 


15-85 


command 15-12 
parameters 
address 

forms of 15-14 


passed to attention handling routines 2-9 

passed to command processors 2-5 

received by attention handling routines 2-9 
parenthesized string (PSTRING) format of 15-20 
PARM field of LOGON EXEC statement 2-2 
parse acceptance of double-byte character set data 

in aconstant string 15-24 


in a parenthesized string 15-20 
in a quoted character string 15-26 
in a quoted string 15-23 
in a self-delimiting string 15-14 
in a value string 15-14 
no translation to upper case 15-83 
shift-in character 15-8 
shift-out character 15-8 
parse macro instructions 15-10, 15-30 


coding examples 15-98 
combining LIST and RANGE options’ 15-78 
description 15-30 
IKJENDP 15-57 
IKJIDENT 15-47 
IKJIKEYWD 15-53 
IKJINAME 15-54 
IKJOPER 15-41 
IKJPARM 15-31 
IKJPOSIT 15-32 
IKJRLSA = 15-58 
IKJRSVWD 15-44 
IKJSUBF 15-57 
IKJTERM 15-36 
LIST option 15-76 


order of coding for positional parameters 
purpose of 1-4 
RANGE option 15-77 

parse service routine (IKJPARS) 15-1 
character types recognized 15-8 
command processor use of 3-6, 15-10 
entry point 15-1 


examples of use 15-10, 15-87 


insertion of default values 15-83 
insertion of keywords 15-85 
issuing second level messages 15-85 
macro instruction description 15-30 
operation of 15-2 
parameter description list 

example 15-98 
parse parameter list (PPL) 15-59 


passing control to 15-58 
passing control to a validity checking routine 
positional parameters 15-12 
prompt mode HELP function 3-6 
passing control 
to command processors 2-3 


15-32 


15-84 


to commands and subcommands_1-3 

to I/O service routines 12-3 

to parse service routine 15-58 

to TEST command processor 2-7 

to the TSO service routines 7-2, 7-3 

to validity checking routine 15-84 
passing message lines 


to PUTGET 12-75 
to PUTLINE 12-51 
password 15-21 


PAUSE processing 8-2, 12-78 
PDE (parameter descriptor entry) 


combining LIST and RANGE options 15-78 
effect of LIST and RANGE options on 
format 15-76 

format (general) 15-60 

types 
ADDRESS parameter 15-64 
CONSTANT 15-70 
DSNAME or DSTHING parameter 15-62 
EXPRESSION _ 15-75 
expression value parameter 15-66 
IKJIDENT parameter 15-75 
JOBNAME parameter 15-63 
KEYWORD parameter 15-83 
non-delimiter dependent parameter 15-75 


positional parameter 15-61 
RESERVED word 15-74 
STATEMENT NUMBER 15-72 
STRING, PSTRING, or a QSTRING 
parameter 15-61 
UID2PSWD _ 15-69 
USERID parameter 
VALUE parameter 
VARIABLE 15-73 
PDL 
header 15-60 
PDL (parameter descriptor list) 
naming (DSECT=)_ 15-60 
perform a list of DAIR operations 10-17 
PGPB, PUTGET parameter block 12-2 


15-69 
15-62 


physical line processing 12-28 
pointer 
forward chain 12-48 


to the formatted line (PUTLINE) 12-56 

to the I/O service routine parameter block 12-2 
positional parameters 15-12 

entered as lists or ranges 

missing 15-12 


15-27, 15-76 


not dependent upon delimiters 15-27 

order of coding parse macros 15-32 
PPMODE 2-5 
primary text segment 

offset of 12-54 
print inhibit (PTBYPS) 12-62, 12-68 
private HELP data set 3-11 
processing 

a source in-storage list 8-2 

attention interruptions 2-8 

modes 11-4, 12-60 
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physical line 12-28 
STOP commands 2-12 
PROFILE command 8-3, 12-53, 12-78 
PROFILE subcommand of TEST 18-3 
program 
areas 
displaying 18-7 
displaying !-6 
execution under TEST 18-5 
interruption at a specified location (TEST) 1-6, 
18-7 
program access to CLIST variables 6-1 
program access to CLIST variables (see CLIST) 
program execution 
examining 18-7 
program interface to CLISTs 5-3 
program interface to other programs 5-3 
program interface to TSO commands _ 5-3 
program residency 
below 16 megabytes 4-2, 4-3 
program status word (PSW) 
displaying 1-6, 18-9 
program-id 
statement number parameter 15-25 
variable parameter 15-24 
prompt message 
processing 12-78 
second level 15-85 
prompt mode HELP function 
definition of 3-6 
importance of ECTNOQPR bit 3-6 
making active for subcommands 3-7 
relationship to second level messages 8-2 
restrictions on 3-6 
updating HELP members for 3-14 
prompting 15-86 
for missing operands 15-86 
inhibiting 12-74 
input wait after 12-79 
messages 8-] 
responses 15-86 
return codes 15-101 
scanning the input buffer 15-1 
translation to upper case 15-83 
types of command parameters recognized 15-12 
user at the terminal 15-86 
using the parse service routine 
examples 15-86 
PROTECT subcommand of TEST 18-3 
protection of screen contents B-4 
PSTRING 
syntax of 15-20 
PSW 
at time of abnormal termination 2-8 
displaying 1-6 
PTPB, PUTLINE parameter block 12-2 
purging the second level message chain 12-57 
PUT macro instruction 11-3 
PUTGET attention ECB 12-67 
PUTGET buffer 
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freeing 12-79 
PUTGET macro instruction 
coding example 12-81 2 
format 12-61, 12-66 
OUTPUT=0_ 12-77 
PUTGET parameter block 12-72 
initializing 12-72 
PUTGET processing 12-77 
PUTGET service routine 12-60 
barrier elements on the stack 12-65, 12-71 
basic functions of 1-3 
coding example 12-81 
command processor use of 3-4 
control blocks 12-76, 12-80 
description 12-60 
input buffer format 12-79 
input line format 12-79 
macro instruction 
execute form 12-65 
list form 12-61 
mode message processing 12-77 
no output line 12-77 
operands 12-61, 12-66 
output line descriptor (OLD) 12-75 
output line formats 12-74 
parameter block (PGPB) 12-72 
passing message lines to 12-75 
PAUSE processing 12-78 
processing of second level messages 8-2 
prompt message processing 12-78 . 
providing the GET (ATTN) function only 12-62 A 
question mark processing 12-78 
return codes 12-83 
sources of input 12-60, 12-77 
text insertion 12-75 
TGET options (TERMGET) 12-64, 12-70 
TPUT options (TERMPUT) 12-62, 12-68 
types of output line descriptor 12-75 
user abend 204 12-84 
PUTLINE functions for message lines 12-50 
PUTLINE macro instruction 
coding example 12-47 
format of 12-35, 12-36 
PUTLINE parameter block 12-45 
initializing 12-44 
PUTLINE service routine 12-35 
basic functions of 1-3 
building a second-level informational chain 12-57 
coding examples of 12-55 
command processor use of 3-4 
control blocks 12-52 
control flags 12-45 
description 12-35 
format only function 12-56 
macro instruction 
execute form 12-39 
list form 12-36 
message line processing 12-53 
message processing control blocks 12-52 <a 
operands 12-36, 12-39 


output 
display when barrier elements exist on the 
stack 12-36, 12-41 
output line descriptor (OLD) 
for multilevel message 12-51 
for single level message 12-51 
output lines 
format 12-46 
parameter block 12-45 
passing message lines to 12-51 
processing of second level messages 8-2, 12-50 
PUTLINE parameter block (PTPB) 12-44 
return codes 12-60 
stripping message identifiers 12-53 
text insertion function 12-54 
TPUT (TERMPUT) options 12-37, 12-41 
types and formats of output lines 12-46 
PUTLINE, putting a line out to the terminal 12-35 
PUTX macro instruction 11-3 
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QSAM 
macro instructions 11-1 
using for terminal I/O 11-1 
QSTRING definition 15-23 
qualification 
variable parameter 15-25 
qualified address parameter 15-15 
formats 15-15 
qualifier 
data name 15-25 
QUALIFY subcommand of TEST 18-2 
question mark 
entered after ABEND 2-7 
processing 12-77 
processing by I/O service routines 12-1 
quoted string (QSTRING) 
syntax of 15-23 
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range 
use of (general) 15-28 
range option 
how to use 15-77 
READ macro instruction 11-3 
read partition query structured field 13-7 
reading a record from the terminal (the READ macro 
instruction) 11-3 
reason codes-IKJEFTSR 5-8 
receive control 
in 24-bit addressing mode 4-2 
in 31-bit addressing mode 4-3 
record formats supported under TSO 11-4 


record returned by GETLINE 
identifying the source of 12-29 
reentering full-screen mode B-4 
register 
changing contents 1-6, 18-9 
displaying 1-6 
floating-point 15-14 
general 15-14 
register contents 
when TMP is attached 2-2 
register form 
TPUT macro 13-2 
relationship between primary and secondary segments 
(PUTLINE) 12-54 
relative address parameter 15-14 
RENAME subcommand of TEST 18-3 
requesting 
acommand 2-3 
a new command or subcommand 1-4 
RESHOW B-4, B-7 
residency 
input 
above or below 16 megabytes 4-4 
above 16 megabytes 4-3, 4-4, 4-5 
below 16 megabytes 4-2, 4-3, 4-4, 4-5 
program 4-1 
requirements 4-3 
responding to 
abnormal terminations 1-4 
attention interruptions 1-4 
restoration of screen contents B-4 
restrictions 
addressing for TEST 18-4 
non-delimiter dependent parameters 15-27 
on executing exclusively in 31-bit mode 4-3 


on invoking programs with 24-bit dependencies 4-3 


when issuing commands on a user-written 
TMP 2-1 
results of command scan 15-8 
retrieving information about commands and 
subcommands 3-10 
return codes 
from command scan_ 15-9 
from DAIR 10-23 
from dynamic allocation 10-24 
from GETLINE 12-34 
from GTDEVSIZ 14-2 
from GTSIZE 14-3 
from GITERM 14-4 
from IKJEHCIR 16-3 
from LOCATE 16-3 
from parse service routine 15-101 
from PUTGET 12-83 
from PUTLINE 12-60 
from RTAUTOPT 14-5 
from SPAUTOPT 14-6 
from STACK 12-21 
from STATIN 14-7 
from STAUTOCP 14-8 
from STAUTOLN 14-10 
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from STAX 9-10 

from STBREAK 14-11 

from STCC 14-14 

from STCLEAR 14-14 

from STCOM 14-15 

from STFSMODE 14-17 

from STLINENO 14-18 

from STSIZE 14-20 

from STTIMEOU 14-21 

from STTMPMD 14-22 

from STTRAN 14-24 

from TCLEARQ 14-25 

from TGET 13-12 

from TPG 13-9 

from TPUT 13-7 

validity checking 15-85 
return codes-IKJEFTSR 5-7 
returning the value of a variable 6-8 
RMODE= ANY 

AMODE=31 4-3 
RMODE = 24 

AMODE=ANY 4-2 

AMODE=24 4-2 

AMODE=31 4-3 
RTAUTOPT macro instruction 14-4 
RUN subcommand of TEST 18-2 
running programs 

in 370-XA mode 4-2 

on an MVS/XA system 4-1 

on an MVS/370 system 4-1 
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SAM terminal routines 11-2 
screen contents 
protection B-4 
restoration of B-4 
second level messages 
definition 8-1 
deleting 3-4, 8-3 
informational messages 12-57 
message chain 3-4, 12-57 
messages handled by parse 15-85 
no message identifiers 12-57 
requesting 8-1 
secondary text segment 
offset of 12-54 
SEND subcommand of TEST 18-3 
separator characters 15-8, 15-12 
sequence of operations 
TEST 18-6 
sequential access method (SAM) terminal routines 
CHECK 11-4 
GET 11-3 
PUT 11-3 
PUTX 11-3 
READ 11-3 
WRITE 11-4 
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service routine interfaces 
catalog information routine (IKJEHCIR) 4-4, 7-4, 
16-1 
CLIST variable access routine (IKJCT441) 4-4 
command scan service routine (IKJSCAN) 7-4, 
15-5 
DAIR_ 10-2 
DAIRFAIL (IKJEFF18) 4-4, 10-24 
data type processor (IKJEBEPS) 4-4 
default service routine (IKJEHDEF) 4-4, 7-4, 17-1 
dynamic allocation interface routine 
(IKJDAIR) 4-4, 7-4 
GETLINE service routine (IKJGETL) 4-4, 12-4 
GNRLFAIL/VSAMFAIL (IKJEFF19) 4-4, 10-26 
parse service routine (IKJPARS) 4-4, 7-4, 15-9 
PUTGET service routine (IKJPTGT) 4-4, 12-4 
PUTLINE service routine (IKJPUTL) 4-4, 12-4 
STA interface routine (IKJEHSIR) 4-4 
STACK service routine (IKJSTCK) 4-4, 12-4 
STAX 4-4, 9-1 
TSO message issuer routine (IKJEFFO2) 4-4, 7-4, 
8-3 
TSO service routine (IKJEFTSR) 4-4 
set full-screen mode on B-2 
setting 
addressing modes 
via BASSM or BSM_ 7-4 
shift-in character 15-8, 15-13 
shift-out character 15-8, 15-13 
single level messages 12-50 
single line data 12-46 
source 
effects on message processing 8-2 
source data set 
in storage 12-12 
adding an element to the input stack 12-6, 
12-10 
sources of input 12-12 
changing 12-5 
current 12-5 
space parameter 
definition 15-23 
SPAUTOPT macro instruction 14-5 
special functions of the TMP 2-12 
STACK macro instruction 12-5 
execute form 12-8 
list form 12-5 
stack parameter block (STPB) 12-14 
STACK service routine 12-5 
basic functions of 1-3 
coding example of macro 12-13, 12-16 
command processor use of 3-3 
control block structures 
in-storage list 12-18 
description 12-5 
element code 12-13 
input source 12-12 
list source descriptor (LSD) 12-14 
macro instruction 
execute form 12-8 


list form 12-5 

parameter block 12-13 

return codes 12-21 
STAE macro 3-7 
STAI operand of ATTACH macro 3-7 
standard form 

TGET macro 13-10 

TPUT macro 13-2 
STATTN macro instruction 14-6 
STATUS subcommand of TEST 18-3 
STAUTOCP macro instruction 14-8 
STAUTOLN macro instruction 14-9 
STAX parameter list (STPL) 9-7 
STAX service routine 9-1 

coding example of macro 9-8 

deferring attention exits 9-2 

macro instruction format 9-4 

parameter list 9-7 
STBREAK macro instruction 14-10 
STCC macro instruction 14-12 
STCLEAR macro instruction 14-14 
STCOM macro instruction 14-14 
STFSMODE B-1, B-2 
STFSMODE macro instruction 14-15 
STLINENO  B-1 
STLINENO macro instruction 14-17 
STOP command processing 2-12 
STOP/MODIFY event control block (ECB) 2-12 
Storage areas 

displaying 18-7 
STPB, STACK parameter block 12-2 
string 

definition 15-13 
stripping message identifiers 12-53 
STSIZE macro instruction 14-18 
STTIMEOU macro instruction 14-20 
STTMPMD B-1 
STTMPMD macro instruction 14-21 
STTRAN macro instruction 14-22 
subcommand name 

checking syntax 1-3 

syntactically valid 15-1 
subcommand processors 

abnormally terminating 3-7 
subcommands of TEST 18-2 
subfield descriptions 15-57 
subfields associated with keyword parameters 15-57 
SUBMIT subcommand of TEST 18-3 
subscript 

statement number parameter 15-25 

variable parameter 15-25 
substitute mode of PUT and PUTX macros 11-3 
subtask ABEND 2-6 
SVC 93 13-1 
symbolic address 

for TEST 18-4 

syntax of 15-15 
SYNCH macro instruction 

to invoke TEST command processor 2-7 
syntax 


notation for defining macro instructions A-1 
SYSABEND data set 2-8 
SYSMDUMP data set 2-8 
SYSOUT data set 

allocation of 10-18 
SYSOUTLINE 6-1 
system catalog 

searching for data set name _ 10-5 
system code 337 11-3 
SYSUDUMP data set 2-8 
SYSI.CMDLIB 3-2 
SYS1.HELP - the HELP data set 

attributes of 3-10 

updating 3-11 


TAXE 9-1 
TCLEARQ macro instruction 14-24 
TERM =TS (operand of DD statement) 11-5 
terminal 
allocating a data set to 10-14 
communicating with 1-2 
terminal as input source 12-12, 12-16 
terminal attention exit element (TAXE) 9-1 
terminal attention interruption element (TAIE) 2-11 
TERMINAL BREAK 
use of B-3 
terminal control macro instruction 14-1 
terminal element 
adding to input stack 12-5, 12-10 
barrier elements (dividing the input stack into 
substacks) 12-5, 12-6, 12-10 
coding example 12-16 
terminal monitor program (TMP) 
basic functions 1-2 
conditions to which it must respond 2-2 
control blocks passed to command processors 7-3 
description 1-1 
ESTAE exit 2-7 
fresh copy after ABEND 2-8 
functions of 1-2 
initialization 2-2 
intercepting a task ABEND 2-5, 2-7 
link to TEST command processor 2-7 
obtaining acommand 2-3 
parameters passed to a command processor 2-5 
processing a CLIST attention exit 2-8 
processing a STOP command 2-12 
processing an attention interruption 2-8 
restrictions for issuing commands on a user-written 
TMP 2-1 
shared subpool 2-3 
special functions of 2-12 
STOP/MODIFY ECB 2-12 
TIME function 2-12 
using command scan 2-12 
TERMINAL subcommand of TEST 18-3 
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terminal user’s options after ABEND 2-7 
TEST command 

addressing restrictions 18-4 
ALLOCATE subcommand 18-2 
AND subcommand 18-2 
AT subcommand 18-7 
breakpoints 

establishing and removing 18-7 
changing 

data areas 18-9 

instructions 18-9 

register contents 18-9 
CP or NOCP operand 18-5 
definition 17-1 
determining data set information 18-11 
displaying selected areas of storage 18-7 
entering the command 18-6 
EQUATE subcommand 18-2 
establishing and removing breakpoints 18-7 
executing a program under control of 18-5 
forcing execution of program subroutines 18-10 
GETMAIN subcommand 18-2, 18-9 
issuing the 18-6 
LIST subcommand 18-2, 18-8 
LISTDCB subcommand 18-9 
LISTDEB subcommand 18-8 
LISTMAP subcommand 18-8 
LISTPSW subcommand 18-9 
LISTTCB subcommand 18-8 
NOCP or CP operand 18-5 
OFF subcommand 18-2, 18-7 
OR subcommand 18-2, 18-3 
PROFILE subcommand 18-3 
PROTECT subcommand 18-3 
QUALIFY subcommand 18-3 
RENAME subcommand 18-3 
restrictions 

addressing 18-4 
SEND subcommand 18-3 
sequence of operations 18-6 
STATUS subcommand 18-3 
subcommands 18-2 
SUBMIT subcommand 18-3 
symbol processing 18-4 
testing a newly-written TMP or CP 17-1 
testing after a program ABEND 18-10 
UNALLOC subcommand 18-3 
when to use 18-3 
WHERE subcommand 18-2, 18-10 


testing 
currently executing program 18-3 
online 1-5 


program not currently executing 18-4 
testing a CP 1-5 
testing a TMP 1-5 
testing a TMP or CP 17-1 
text insertion function of PUTLINE 12-54 
TGET  B-1, B-3 

basic functions 1-3 

coding example 13-17 
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definition 13-10 
execute form 13-10 
format 13-10 
list form 13-10 
macro description 13-10 
number of bytes moved 13-11 
register form 13-10 
return codes 13-12 
standard form 13-10 
transmitting 3270 extended data stream functions 
via TGET 14-16 
used by GET 11-3 
used by READ 11-3 
TGET ASIS_ B-3 
TGET/TPUT SVC 
parameter registers 13-13 
TGET/TPUT/TPG SVC _ 13-1 
macro instructions 13-1, 13-7 
TIME function of the TMP 2-12 
TPG B-3 
basic functions 1-3 
codes returned by 13-9 
definition 13-7 
execute form 13-8 
list form 13-8 
macro description 13-8 
return codes 13-9 
standard form 13-8 
TPUT B-1, B-3 
basic functions 1-3 
codes returned by 13-7 
coding example 13-17, 13-18 
definition 13-1 
execute form 13-2 
list form 13-2 
macro description 13-1 
register form 13-2 
return codes 13-7 
standard form 13-2 
transmitting 3270 extended data streams via TPUT 
NOEDIT 13-4 
used by PUT and PUTX 11-3 
used by WRITE 11-4 
TPUT FULLSCR_ B-3 
TPUT NOEDIT  B-3 
translation to upper case 15-83 
TSEVENT macro instruction 2-5 
TSO I/O service routines 12-1 
TSO message issuer routine (IKJEFFO02) 8-3 
TSO service facility 
See TSO service routine 
TSO service routine 
ABEND processing 5-5, 5-6 
ABEND reason code 5-6 
flags 5-5 
function buffer 5-6 
function buffer length 5-6 
function flag 5-6 
command 5-6 
program 5-6 


function reason code 5-6 
function return code 5-6 
Cc IKJEFTSR description 1-1 
IKJEFTSR return codes 5-7 
introduction 5-1] 
invoking the TSO service routine 5-3 
optional parameter 5-7 
parameters 5-5, 5-6, 5-7 
ABEND processing 5-5 
ABEND reason code _ 5-6 
command function flag 5-6 
fifth parameter 5-6 
first parameter 5-5, 5-6 
flags 5-5 
fourth parameter 5-6 
function buffer 5-6 
function flag 5-6 
function reason code 5-6 
function return code 5-6 
functional parameter list 5-7 
program function flag 5-6 
program parameter list 5-7 
second parameter 5-6 
seventh parameter 5-7 
sixth parameter 5-6 
third parameter 5-6 
program interface to TSO commands or 
programs 5-3 
second parameter 5-6 
function buffer 5-6 
YL their uses and interfaces 
IKJDAIR 10-2 
TSO service routines 
control blocks 
IKJCPPL 7-1 
IKJCSOA_ 7-1 
IKJCSPL 7-1 
IKJDAPL 7-1 
IKJDAPOC 7-1 
IKJDAPO00 
IKJDAP04 
IKJDAP08 
IKJDAPIC 
IKJDAP10 
IKJDAP14 
IKJDAP18 
IKJDAP2C 
IKJDAP24 
IKJDAP28 
IKJDAP30 
IKJDAP34 
IKJDFPB 7-1 
IKJDFPL 7-1 
IKJECT 7-1 
IKJEFFDF 7-1 
IKJEFFGF 7-1 
IKJEFFMT 7-1 
IKJEGTPB 7-1 
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IKJPGPB 7-1 


IKJPPL 7-1 
IKJPSCB_ 7-1 
IKJPTPB 7-1 
IKJSTPB 7-1 
IKJSTPL 7-1 
IKJTAIE 7-1 
IKJTAXE 7-1 
IKJTMPWA_ 7-1 
IKJTPL 7-1 
IKJUPT 7-1 


processing terminal requests 6-14 
their uses and interfaces 
IKJCSOA 15-6 
IKJCSPL 15-5 

IKJENDP 15-57 
IKJGTPB 12-29 
IKJIDENT 15-46 
IKJIOPL 12-2 
IKJKEYWD 15-52 
IKJNAME 15-54 
IKJOPER 15-40 
IKJPARM 15-31 . 
IKJPOSIT 15-32 
IKJPPL 15-10 
IKJRLSA = 15-58 
IKJRSVWD = 15-44 
IKJSUBF 15-56 
passing control to 7-2 

TSOLNK_ 5-3 

TSVT 6-1 


UID2PSWD 
definition 15-21 
UNALLOC subcommand of TEST 18-3 
update the value of a variable 6-3, 6-5 
updating existing HELP members 3-15 
updating SYS1.HELP 3-11 
user 
communicating with 1-2 
user abends 
PUTGET service routine (204) 12-84 
user LOGON PROC 2-1 
DYNAMNBR parameter on EXEC statement 2-1 
example 2-1 
userid 
definition and format 15-21 
using 
BSAM for terminal I/O 10-27 
command scan service routine (IKJSCAN) 15-3 
DAIR_ 10-2 
parse macro instructions 15-30 
parse service routine (IKJPARS) 15-9 
PUTLINE format only function 12-56 
PUTLINE text insertion function 12-54 
QSAM for terminal 1/O 10-27 
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TGET/TPUT/TPG SVC for terminal I/O 


TSO I/O service routines 12-1 
VTAM full-screen mode _ B-1 
utility data set allocation 10-8 


validity check parameter list 15-85 
validity checking exits 3-6 
value parameter definition 15-14 


variable parameter 15-24 
variables 
CLIST 6-1 


control 6-1 
verb number 


statement number parameter 15-25 
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displaying 1-6 
VSAMFAIL routine 
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